Общий формат запросов

Общий вид запросов к Yandex Tracker API:

<метод> https://api.tracker.yandex.net/v3/<тип_ресурса>/<идентификатор_ресурса>/?<параметр>=<значение>
Структура запроса
<метод> /v3/<тип_ресурса>/<идентификатор_ресурса>/?<параметр>=<значение>
Host: api.tracker.yandex.net
Authorization: OAuth <OAuth-токен>
X-Org-ID или X-Cloud-Org-ID: <идентификатор_организации>

{
   Тело запроса в формате JSON
}
Python
import requests;

def my_function():
    session = requests.Session()
    url = "https://api.tracker.yandex.net/v3/<resources>/<resource_id>/?<param>=<value>"
    json = {
        # Тело запроса в формате JSON
    }
    head =  {
        "Authorization": "OAuth <OAuth-токен>",
        "X-Org-ID": <идентификатор_организации>
    }
    session.headers.update(head)
    response = session.post(url, json=json) # session.* - get, post, path, delete
    data = response.json()
    print(response)
    print(data)

my_function()

Примечание

Yandex Tracker API передает и получает параметры даты и времени в часовом поясе UTC±00:00. Поэтому полученные время и дата могут отличаться от часового пояса клиента, с которого выполняется запрос.

Методы

Запросы к Tracker API используют один из HTTP-методов:

GET — получить информацию об объекте или списке объектов;

POST — создать объект;

PATCH — изменить параметры существующего объекта. Запросы, выполненные с помощью метода PATCH изменяют только те параметры, которые явно указаны в теле запроса;

DELETE — удалить объект.

Ресурс

Адрес ресурса в запросе содержит версию API Yandex Tracker:

  • v3 — текущая версия, в которой доступны все обновления методов API. Рекомендуется использовать эту версию для всех запросов к API.

  • v2 — предыдущая версия. В запросах можно использовать версию v2, при этом могут быть недоступны новые методы API и параметры объектов Tracker.

Заголовки

В запросах к Tracker API указывайте заголовки:

  • Host: api.tracker.yandex.net

  • Authorization: OAuth <OAuth-токен> — при доступе по протоколу OAuth 2.0. Подробнее в разделе Получить доступ к API по протоколу OAuth 2.0.

    Authorization: Bearer <IAM-токен> — при доступе при помощи IAM-токена. Подробнее в разделе Получить доступ к API по IAM-токену.

    Например: Authorization: Bearer t1.ab123cd45*****************.

  • X-Org-ID или X-Cloud-Org-ID: идентификатор организации.

    • Используйте заголовок X-Org-ID, если к Tracker привязана организация Яндекс 360 для бизнеса.

    • Используйте заголовок X-Cloud-Org-ID, если к Tracker привязана организация Yandex Cloud Organization.

    Чтобы узнать идентификатор организации, перейдите на страницу Администрирование → Организации и скопируйте значение поля идентификатор.

    Например: X-Org-ID: 1234***.

  • Accept-Language: <тег языка> — язык локализации.

    По умолчанию HTTP-запрос возвращает локализованные поля на русском языке. Чтобы получить значения локализованных полей на английском языке, укажите заголовок с тегом en.

Формат тела запроса

В теле запроса передается JSON-объект с идентификаторами изменяемых полей задачи и их значениями.

  • Чтобы добавить или удалить значение из массива, используйте команды add и remove:

    •     {
        "followers": { "add": ["<идентификатор_сотрудника_1>", "<идентификатор_сотрудника_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.
  • Чтобы добавить значения из полей задачи, используйте переменные.

Использование специальных символов

При передаче параметров строкового типа учитывайте особенности работы со специальными символами:

  • Символы ", \, / необходимо экранировать с помощью обратного слеша \.
  • Для переноса строки используйте символы \n или \r.
  • Символы в кодировке Unicode можно вставить в формате \uFFFF.

Например, в тексте описания задачи могут встречаться двойные кавычки или символы переноса строки:

{
  "description": "Внесите исправления:\n1. Используйте значение \"1\" вместо значения \"2\"."
}

Постраничное отображение результатов

Если вы запрашиваете список объектов, и количество строк в ответе больше 50, в ответе возвращается страница с указанным количеством результатов. Вы можете выполнить несколько запросов для просмотра последующих страниц. Для этого используется механизм постраничного отображения результатов.

При постраничном отображении результаты запроса рассчитываются каждый раз при отображении новой страницы. Если за время просмотра одной страницы в результатах запроса произошли изменения, это может повлиять на отображение следующих страниц. Например, по запросу найдено 11 задач, из которых отображено 10. В процессе просмотра результатов первой страницы одна из задач была изменена и перестала отвечать требованиям поискового запроса. В этом случае, при запросе второй страницы результатов будет возвращен пустой массив, так как оставшиеся 10 задач будут находиться на первой странице.

В новом API доступно постраничное отображение результатов запроса для событий и комментариев с более гибкими настройками.

Для постраничного отображения результатов используйте в запросе следующие параметры:

  • perPage (необязательный)

    Количество объектов (задач, очередей и пр.) на странице. Значение по умолчанию — 50.

  • page (необязательный)

    Номер страницы ответа. Значение по умолчанию — 1.

В ответе будут содержаться следующие заголовки:

  • X-Total-Pages

    Общее количество страниц с записями.

  • X-Total-Count

    Общее число записей в ответе.

Примеры запросов

Пример 1: Изменить название, описание, тип и приоритет задачи.
  • Используется HTTP-метод PATCH.
  • Редактируется задача TEST-1.
  • Новый тип задачи: «Ошибка».
  • Новый приоритет задачи: «Низкий».

PATCH

https://api.tracker.yandex.net/v3/issues/TEST-1
PATCH /v3/issues/TEST-1
Host: api.tracker.yandex.net
Authorization: OAuth <OAuth-токен>
X-Org-ID или X-Cloud-Org-ID: <идентификатор_организации>
{
  "summary": "<новое_название_задачи>",
  "description": "<новое_описание_задачи>",
  "type": {
      "id": "1",
      "key": "bug"
      },
  "priority": {
      "id": "2",
      "key": "minor"
      }
}

import requests;

def my_function():
    session = requests.Session()
    url = "https://api.tracker.yandex.net/v3/issues/TEST-1"
    json = {
        "summary": "<новое_название_задачи>",
        "description": "<новое_описание_задачи>",
        "type": {
            "id": "1",
            "key": "bug"
            },
        "priority": {
            "id": "2",
            "key": "minor"
            }
        }
    head =  {
        "Authorization": "OAuth <OAuth-токен>",
        "X-Org-ID": <идентификатор_организации>
    }
    session.headers.update(head)
    response = session.patch(url, json=json)
    data = response.json()
    print(response)
    print(data)

my_function()
Пример 2: Запрос одной задачи с указанием необходимых полей.
  • Используется HTTP-метод GET.
  • В ответе включено отображение приложений.

GET

https://api.tracker.yandex.net/v3/issues/JUNE-3?expand=attachments
GET /v3/issues/JUNE-3?expand=attachments
Host: api.tracker.yandex.net
Authorization: OAuth <OAuth-токен>
X-Org-ID или X-Cloud-Org-ID: <идентификатор_организации>

import requests;

def my_function():
    session = requests.Session()
    url = "https://api.tracker.yandex.net/v3/issues/JUNE-3?expand=attachments"
    head =  {
        "Authorization": "OAuth <токен>",
        "X-Org-ID": <идентификатор_организации>
    }
    session.headers.update(head)
    response = session.get(url)
    data = response.json()
    print(response)
    print(data)

my_function()
Пример 3: Создать задачу.
  • Используется HTTP-метод POST.
  • Создается задача с названием «Test Issue» в очереди с ключом «TREK».
  • Новая задача — подзадача «JUNE-2».
  • Тип создаваемой задачи – «Ошибка».
  • Исполнитель задачи – <логин_пользователя>

POST

https://api.tracker.yandex.net/v3/issues/
POST /v3/issues/ HTTP/1.1
Host: api.tracker.yandex.net
Authorization: OAuth <OAuth-токен>
X-Org-ID или X-Cloud-Org-ID: <идентификатор_организации>
{
  "queue": "TREK",
  "summary": "Test Issue",
  "parent":"JUNE-2",
  "type": "bug",
  "assignee": "<user_login>",
  "attachmentIds": [55, 56]
}

import requests;

def my_function():
    session = requests.Session()
    url = "https://api.tracker.yandex.net/v3/issues/"
    json = {
        "queue": "TREK",
        "summary": "Test Issue",
        "parent":"JUNE-2",
        "type": "bug",
        "assignee": "<user_login>",
        "attachmentIds": [55, 56]
        }
    head =  {
        "Authorization": "OAuth <токен>",
        "X-Org-ID": <идентификатор_организации>
    }
    session.headers.update(head)
    response = session.post(url, json=json)
    data = response.json()
    print(response)
    print(data)

my_function()
Пример 4: Найти задачи очереди, которые назначены на заданного сотрудника. Результаты отобразить постранично.
  • Используется HTTP-метод POST.
  • Ключ очереди – «TREK».
  • Исполнитель задачи – <логин_пользователя>.

POST

https://api.tracker.yandex.net/v3/issues/_search?perPage=15
POST /v3/issues/_search?perPage=15
Host: api.tracker.yandex.net
Authorization: OAuth <OAuth-токен>
X-Org-ID или X-Cloud-Org-ID: <идентификатор_организации>
{
  "filter": {
    "queue": "TREK",
    "assignee": "<user_login>"
  }
}

import requests;

def my_function():
    session = requests.Session()
    url = "https://api.tracker.yandex.net/v3/issues/_search?perPage=15"
    json = {
        "filter": {
            "queue": "TREK",
            "assignee": "<user_login>"
            }
        }
    head =  {
        "Authorization": "OAuth <токен>",
        "X-Org-ID": <идентификатор_организации>
    }
    session.headers.update(head)
    response = session.post(url, json=json)
    data = response.json()
    print(response)
    print(data)

my_function()
Предыдущая
Доступ к API
Следующая
Получить параметры задачи