Общий формат запросов
Общий вид запросов к Yandex Tracker API:
<метод> /v2/<resources>/<resource_id>/?<param>=<value>
Host: https://api.tracker.yandex.net
Authorization: OAuth <токен>
X-Org-ID: <идентификатор организации>
{
Тело запроса в формате JSON
}
Примечание
Yandex Tracker API передает и получает параметры даты и времени в часовом поясе UTC±00:00. Поэтому полученные время и дата могут отличаться от часового пояса клиента, с которого выполняется запрос.
Методы
Запросы к Tracker API используют один из HTTP-методов:
GET
— получить информацию об объекте или списке объектов;
POST
— создать объект;
PATCH
— изменить параметры существующего объекта. Запросы, выполненные с помощью метода PATCH изменяют только те параметры, которые явно указаны в теле запроса;
DELETE
— удалить объект.
Заголовки
В запросах к Tracker API указывайте заголовки:
-
Host: https://api.tracker.yandex.net
-
Authorization: OAuth <ваш OAuth-токен>
— при доступе по протоколу OAuth 2.0.Authorization: Bearer <ваш IAM-TOKEN>
— при доступе по IAM-токену. -
X-Org-ID: <идентификатор организации>
Чтобы узнать идентификатор организации, перейдите на страницу настроек Tracker. Идентификатор указан в поле ID организации для API.
Формат тела запроса
В теле запроса передается JSON-объект с идентификаторами изменяемых полей задачи и их значениями.
-
Чтобы добавить или удалить значение из массива, используйте команды
add
иremove
:-
{ "followers": { "add": ["<id сотрудника1>", "<id сотрудника2>"] } }
Команда
add
добавляет новые значения в массив. Чтобы перезаписать массив (удалить старые значения и добавить новые), используйте командуset
. -
-
Чтобы обнулить значение поля, укажите значение
null
. Чтобы обнулить массив, используйте пустой массив[]
. Отдельные значения в массиве можно изменить с помощью командtarget
иreplacement
:{"followers": null}
-
{ "followers": { "replace": [ {"target": "<идентификатор1>", "replacement": "<идентификатор2>"}, {"target": "<идентификатор3>", "replacement": "<идентификатор4>"}] } }
-
Например, чтобы изменить тип задачи на
Ошибка
, используйте один из способов:{"type": 1}
{"type": "bug"}
-
{ "type": { "id": "1" } }
-
{ "type": { "name": "Ошибка" } }
-
{ "type": {"set": "bug"} }
Формат текста и переменные
При работе с запросами на создание или редактирование комментариев, макросов, триггеров и автодействий используйте специальный формат для оформления текста сообщения:
- Чтобы отформатировать текст, используйте разметку Yandex Flavored Markdown.
- Чтобы добавить перенос строки, используйте символ
\n
. - Чтобы добавить значения из полей задачи, используйте переменные.
Постраничное отображение результатов
Если вы запрашиваете список объектов, и количество строк в ответе больше 50, в ответе возвращается страница с указанным количеством результатов. Вы можете выполнить несколько запросов для просмотра последующих страниц. Для этого используется механизм постраничного отображения результатов.
При постраничном отображении результаты запроса рассчитываются каждый раз при отображении новой страницы. Таким образом, если за время просмотра одной страницы в результатах запроса произошли изменения, это может повлиять на отображение следующих страниц. Например, по запросу найдено 11 задач, из которых отображено 10. В процессе просмотра результатов первой страницы одна из задач была изменена и перестала отвечать требованиям поискового запроса. В этом случае, при запросе второй страницы результатов будет возвращен пустой массив, так как оставшиеся 10 задач будут находиться на первой странице.
Для постраничного отображения результатов используйте в запросе следующие параметры:
-
perPage (необязательный)
Количество объектов (задач, очередей и пр.) на странице. Значение по умолчанию — 50.
-
page (необязательный)
Номер страницы ответа. Значение по умолчанию — 1.
В ответе будут содержаться следующие заголовки:
-
X-Total-Pages
Общее количество страниц с записями.
-
X-Total-Count
Общее число записей в ответе.
Примеры запросов
- Используется HTTP-метод PATCH.
- Редактируется задача TEST-1.
- Новый тип задачи:
Ошибка
. - Новый приоритет задачи:
Низкий
.
PATCH /v2/issues/TEST-1
Host: https://api.tracker.yandex.net
Authorization: OAuth <OAuth-токен>
X-Org-ID: <идентификатор организации>
{
"summary": "Новое название задачи",
"description": "Новое описание задачи",
"type": {
"id": "1",
"key": "bug"
},
"priority": {
"id": "2",
"key": "minor"
}
}
- Используется HTTP-метод GET.
- В ответе включено отображение приложений.
GET /v2/issues/JUNE-3?expand=attachments
Host: https://api.tracker.yandex.net
Authorization: OAuth <OAuth-токен>
X-Org-ID: <идентификатор организации>
- Используется HTTP-метод POST.
- Создается задача с названием
Test Issue
в очереди с ключомTREK
. - Новая задача является подзадачей
JUNE-2
. - Тип создаваемой задачи –
Ошибка
. - Исполнитель задачи – <user_login>
POST /v2/issues/ HTTP/1.1
Host: https://api.tracker.yandex.net
Authorization: OAuth <OAuth-токен>
X-Org-ID: <идентификатор организации>
{
"queue": "TREK",
"summary": "Test Issue",
"parent":"JUNE-2",
"type": "bug",
"assignee": "<user_login>",
"attachmentIds": [55, 56]
}
- Используется HTTP-метод POST.
- Ключ очереди –
TREK
. - Исполнитель задачи – <user_login>.
POST /v2/issues/_search?perPage=15
Host: https://api.tracker.yandex.net
Authorization: OAuth <OAuth-токен>
X-Org-ID: <идентификатор организации>
{
"filter": {
"queue": "TREK",
"assignee": "<user_login>"
}
}