Связаться с намиПодключиться

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

Статья создана
Улучшена
Обновлена 30 января 2024 г.

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

<метод> /v2/<тип_ресурса>/<идентификатор_ресурса>/?<параметр>=<значение>
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/v2/<resources>/<resource_id>/?<param>=<value>"
    json = {
        # Тело запроса в формате JSON
    }
    head =  {
        "Authorization": "OAuth <OAuth-токен>",
        "X-Org-ID" или "X-Cloud-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 — удалить объект.

Заголовки

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

  • Host: api.tracker.yandex.net

  • Authorization: OAuth <OAuth-токен> — при доступе по протоколу OAuth 2.0.

    Authorization: Bearer <IAM-токен> — при доступе по IAM-токену.

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

    Если у вас только организация Yandex Cloud Organization, используйте заголовок X-Cloud-Org-ID, если только Яндекс 360 для бизнеса или оба типа организаций — X-Org-ID. Чтобы узнать идентификатор организации, перейдите на страницу настроек Tracker. Идентификатор указан в поле ID организации для API.

  • 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.
  • Чтобы добавить значения из полей задачи, используйте переменные.

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

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

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

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

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

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

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

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

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

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

  • X-Total-Pages

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

  • X-Total-Count

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

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

Пример 1: Изменить название, описание, тип и приоритет задачи.
  • Используется HTTP-метод PATCH.
  • Редактируется задача TEST-1.
  • Новый тип задачи: «Ошибка».
  • Новый приоритет задачи: «Низкий».
PATCH /v2/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/v2/issues/TEST-1"
    json = {
        "summary": "<новое_название_задачи>",
        "description": "<новое_описание_задачи>",
        "type": {
            "id": "1",
            "key": "bug"
            },
        "priority": {
            "id": "2",
            "key": "minor"
            }
        }
    head =  {
        "Authorization": "OAuth <OAuth-токен>",
        "X-Org-ID" или "X-Cloud-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 /v2/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/v2/issues/JUNE-3?expand=attachments"
    head =  {
        "Authorization": "OAuth <токен>",
        "X-Org-ID" или "X-Cloud-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 /v2/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/v2/issues/"
    json = {
        "queue": "TREK",
        "summary": "Test Issue",
        "parent":"JUNE-2",
        "type": "bug",
        "assignee": "<user_login>",
        "attachmentIds": [55, 56]
        }
    head =  {
        "Authorization": "OAuth <токен>",
        "X-Org-ID" или "X-Cloud-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 /v2/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/v2/issues/_search?perPage=15"
    json = {
        "filter": {
            "queue": "TREK",
            "assignee": "<user_login>"
            }
        }
    head =  {
        "Authorization": "OAuth <токен>",
        "X-Org-ID" или "X-Cloud-Org-ID": <идентификатор_организации>
    }
    session.headers.update(head)
    response = session.post(url, json=json)
    data = response.json()
    print(response)
    print(data)

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