Подключиться
Yandex Tracker

Найти задачи

Статья создана

Запрос позволяет получить список задач, удовлетворяющих заданному критерию. Если количество задач в ответе более 50, необходимо использовать механизм постраничного отображения.

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

Для поиска задач используйте HTTP-запрос с методом POST. Тело запроса содержит критерии для поиска.

POST /v2/issues/_search?
order=<направление сортировки>
&expand=<дополнительные поля в ответе>
Host: https://api.tracker.yandex.net
Authorization: OAuth <OAuth-токен>
X-Org-ID: <идентификатор организации>

{
  "filter": {
    "<имя поля>": "<значение в поле>"
  },
  "query": "фильтр на языке запросов",
  "expand": "дополнительные поля",
  "keys": "список ключей задач",
  "queue": "ключ очереди"
}
Заголовки

  • Host

    Адрес узла, предоставляющего API:

    https://api.tracker.yandex.net

  • Authorization

    OAuth-токен в формате OAuth <значение токена>, например:

    OAuth 0c4181a7c2cf4521964a72ff57a34a07

  • X-Org-ID

    Идентификатор организации.

Параметры запроса

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

    Направление и поле сортировки задач. Значение указывается в формате [+/-]<название поля>. Знак + или - обозначает направление сортировки.

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

    Дополнительные поля, которые будут включены в ответ:

    • transitions — переходы по жизненному циклу;
    • attachments — вложения.

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

    Количество задач на странице ответа. Значение по умолчанию — 50. Дополнительные параметры показа ответа можно настроить с помощью механизма постраничного отображения.

Тело запроса

Параметр Описание Формат
filter Параметры фильтрации задач. В параметре можно указать название любого поля и значение, по которому будет производиться фильтрация. Объект
query Фильтр на языке запросов. Строка
expand Дополнительные поля, которые будут включены в ответ:
  • transitions — переходы по жизненному циклу;
  • attachments — вложения.
 Строка
keys Список ключей задач. Данный параметр не используется вместе с параметрами filter или quiery. При совместной передаче этих параметров, поиск будет производиться только по keys. Строка
queue Очередь. Данный параметр не используется вместе с параметрами filter или quiery. При совместной передаче этих параметров, поиск будет производиться только по queue. Строка

Параметры queue и keys не используются одновременно с параметрами filter или quiery. При их совместной передаче ответ будет содержать код 400 с сообщением Вы можете использовать только ключи, очередь или поисковый запрос.

Запрос списка задач с указанием дополнительных параметров фильтрации:

  • Используется HTTP-метод POST.
  • Включено постраничное отображение, каждая страница содержит по две записи.
  • В ответе включено отображение приложений.
  • Ответ должен содержать только задачи из очереди JUNE, в которых не указан исполнитель.
POST /v2/issues/_search?scrollType=sorted&amp;perScroll=2&expand=attachments HTTP/1.1
Host: https://api.tracker.yandex.net
Authorization: OAuth <OAuth-токен>
X-Org-ID: <идентификатор организации>
Cache-Control: no-cache

{
  "filter": {
    "queue": "JUNE",
    "assignee": "Empty()"
  }
}

Формат ответа

[
    {
    "self": "https://api.tracker.yandex.net/v2/issues/TREK-9844",
    "id": "593cd211ef7e8a332414f2a7",
    "key": "TREK-9844",
    "version": 7,
    "lastCommentUpdatedAt": "2017-07-18T13:33:44.291+0000",
    "summary": "subtask",
    "parent": {
        "self": "https://api.tracker.yandex.net/v2/issues/JUNE-2",
        "id": "593cd0acef7e8a332414f28e",
        "key": "JUNE-2",
        "display": "Task"
        },
    "aliases": [
            "JUNE-3"
        ],

    "updatedBy": {
        "self": "https://api.tracker.yandex.net/v2/users/1120000000016876",
        "id": "<id сотрудника>",
        "display": "<отображаемое имя сотрудника>"
        },
    "description": "<#<html><head></head><body><div>test</div><div>&nbsp;</div><div>&nbsp;</div> </body></html>#>",
    "sprint": [
            {
        "self": "https://api.tracker.yandex.net/v2/sprints/5317",
        "id": "5317",
        "display": "спринт1"
            }
        ],
    "type": {
        "self": "https://api.tracker.yandex.net/v2/issuetypes/2",
        "id": "2",
        "key": "task",
        "display": "Задача"
        },
    "priority": {
        "self": "https://api.tracker.yandex.net/v2/priorities/2",
        "id": "2",
        "key": "normal",
        "display": "Средний"
        },

    "createdAt": "2017-06-11T05:16:01.339+0000",
    "followers": [
        {
        "self": "https://api.tracker.yandex.net/v2/users/1120000000016876",
        "id": "<id сотрудника>",
        "display": "<отображаемое имя сотрудника>"
        }
        ],
    "createdBy": {
        "self": "https://api.tracker.yandex.net/v2/users/1120000000049224",
        "id": "<id сотрудника>",
        "display": "<отображаемое имя сотрудника>"
        },
    "votes": 0,
    "assignee": {
        "self": "https://api.tracker.yandex.net/v2/users/1120000000049224",
        "id": "<id сотрудника>",
        "display": "<отображаемое имя сотрудника>"
        },
    "queue": {
        "self": "https://api.tracker.yandex.net/v2/queues/TREK",
        "id": "111",
        "key": "TREK",
        "display": "Стартрек"
        },
    "updatedAt": "2017-07-18T13:33:44.291+0000",
    "status": {
        "self": "https://api.tracker.yandex.net/v2/statuses/1",
        "id": "1",
        "key": "open",
        "display": "Открыт"
        },
    "previousStatus": {
        "self": "https://api.tracker.yandex.net/v2/statuses/2",
        "id": "2",
        "key": "resolved",
        "display": "Решен"
        },
    "favorite": false
    },
    {...}
]

Параметры ответа

Параметр Описание Тип данных
self Адрес ресурса API, который содержит информацию о задаче. Строка
id Идентификатор задачи. Строка
key Ключ задачи. Строка
version Версия задачи. Каждое изменение параметров задачи увеличивает номер версии. Число
lastCommentUpdatedAt Дата и время последнего добавленного комментария. Строка
summary Название задачи. Строка
parent Объект с информацией о родительской задаче. Объект
aliases Массив с информацией об альтернативных ключах задачи. Массив строк
updatedBy Объект с информацией о последнем сотруднике, изменявшим задачу. Объект
description Описание задачи. Строка
sprint Массив объектов с информацией о спринте. Массив объектов
type Объект с информацией о типе задачи. Объект
priority Объект с информацией о приоритете. Объект
createdAt Дата и время создания задачи. Строка
followers Массив объектов с информацией о наблюдателях задачи. Массив объектов
createdBy Объект с информацией о создателе задачи. Объект
votes Количество голосов за задачу. Число
assignee Объект с информацией об исполнителе задачи. Объект
queue Объект с информацией об очереди задачи. Объект
updatedAt Дата и время последнего обновления задачи. Строка
status Объект с информацией о статусе задачи. Объект
previousStatus Объект с информацией о предыдущем статусе задачи. Объект
favorite Признак избранной задачи:
  • true — пользователь добавил задачу в избранное;
  • false — задача не добавлена в избранное.
 Логический

Поля объекта parent

Параметр Описание Тип данных
self Ссылка на задачу. Строка
id Идентификатор задачи. Строка
key Ключ задачи. Строка
display Отображаемое название задачи. Строка

Поля объекта updatedBy

Параметр Описание Тип данных
self Ссылка на пользователя. Строка
id Идентификатор пользователя. Строка
display Отображаемое имя пользователя. Строка

Поля объектов массива sprint

Параметр Описание Тип данных
self Ссылка на спринт. Строка
id Идентификатор спринта. Строка
display Отображаемое название спринта. Строка

Поля объекта type

Параметр Описание Тип данных
self Ссылка на тип задачи. Строка
id Идентификатор типа задачи. Строка
key Ключ типа задачи. Строка
display Отображаемое название типа задачи. Строка

Поля объекта priority

Параметр Описание Тип данных
self Ссылка на тип приоритета. Строка
id Идентификатор приоритета. Строка
key Ключ приоритета. Строка
display Отображаемое название приоритета. Строка

Поля объектов массива followers

Параметр Описание Тип данных
self Ссылка на пользователя. Строка
id Идентификатор пользователя. Строка
display Отображаемое имя пользователя. Строка

Поля объекта createdBy

Параметр Описание Тип данных
self Ссылка на пользователя. Строка
id Идентификатор пользователя. Строка
display Отображаемое имя пользователя. Строка

Поля объекта assignee

Параметр Описание Тип данных
self Ссылка на пользователя. Строка
id Идентификатор пользователя. Строка
display Отображаемое имя пользователя. Строка

Поля объекта queue

Параметр Описание Тип данных
self Ссылка на очередь. Строка
id Идентификатор очереди. Строка
key Ключ очереди. Строка
display Отображаемое название очереди. Строка

Поля объекта status

Параметр Описание Тип данных
self Ссылка на статус. Строка
id Идентификатор статуса. Строка
key Ключ статуса. Строка
display Отображаемое название статуса. Строка

Поля объекта previousStatus

Параметр Описание Тип данных
self Ссылка на статус. Строка
id Идентификатор статуса. Строка
key Ключ статуса. Строка
display Отображаемое название статуса. Строка

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

Если под условия запроса попадает более 50 задач, то для их постраничного просмотра необходимо использовать механизм прокрутки результатов.

У механизма прокрутки страниц имеется две разновидности — прокрутка с использованием указанной в запросе сортировки и прокрутка без использования сортировки. Во втором случае результаты поиска возвращаются в произвольном порядке. Прокрутка без использования сортировки эффективнее при получении значительных объемов задач.

Прокрутка без использования сортировки

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

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

    Количество задач на странице. Значение по умолчанию — 50.

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

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

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

  • X-Total-Pages

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

  • X-Total-Count

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

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

Прокрутка с использованием сортировки

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

  • scrollType

    Тип прокрутки. Допустимые значения:

    • sorted — используется указанная в запросе сортировка;
    • unsorted — сортировка не используется.

    Данный параметр не используется совместно с параметрами keys или queue. При совместном использовании этих параметров ответ будет содержать код 400 и сообщение Scroll is not supported.

  • perScroll

    Максимальное количество задач в ответе. Значение по умолчанию — 5000, максимально допустимое значение — 10000.

  • scrollTTLMillis (необязательный параметр)

    Время жизни контекста прокрутки в миллисекундах. Значение по умолчанию — 5000, максимально допустимое значение — 5000.

  • scrollId

    Идентификатор страницы. Параметр указывается, начиная со второго из серии запросов. Значение идентификатора указывается из заголовка X-Scroll-Id ответа на предыдущий поисковый запрос.

  • scrollToken

    Токен, удостоверяющий принадлежность запроса текущему пользователю. Значение идентификатора указывается из заголовка X-Scroll-Token ответа на предыдущий поисковый запрос.

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

  • Link

    Ссылка для перехода на следующую страницу результатов поиска.

  • X-Scroll-Id

    Идентификатор страницы.

  • X-Scroll-Token

    Токен, удостоверяющий принадлежность запроса текущему пользователю.

  • X-Total-Count

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

При данном способе создается слепок результатов поиска и переключение страниц осуществляется в рамках данного слепка. Таким образом, если какая-либо задача будет изменена и перестанет отвечать требованиям поискового запроса, это не повлияет на отображение задачи в слепке результатов поиска. Данный способ является более ресурсоемким. Слепок поиска сохраняется, пока не были просмотрены все страницы с результатами. Если планируется прекратить просмотр результатом поиска не дойдя до конца, необходимо явно освободить занятые ресурсы с помощью запроса Освободить ресурсы просмотра прокрутки.

Возможные коды ответа

200
Запрос выполнен успешно.
В этой статье: