Найти задачи

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

  1. Формат запроса
  2. Формат ответа
  3. Постраничное отображение результатов
  4. Возможные коды ответа

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

Для поиска задач используйте 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": "ключ очереди"
}
Параметры запроса
order (необязательный)

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

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

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

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

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

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

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

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

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

Строка
keys Список ключей задач. Данный параметр не используется вместе с параметрами filter или query. При совместной передаче этих параметров, поиск будет производиться только по keys. Строка
queue Очередь. Данный параметр не используется вместе с параметрами filter или query. При совместной передаче этих параметров, поиск будет производиться только по queue. Строка

Параметры queue и keys не используются одновременно с параметрами filter или query. При их совместной передаче ответ будет содержать код 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

Отображаемое название статуса.

Строка.
Параметр Описание Тип данных
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

Отображаемое название статуса.

Строка.

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

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

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

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

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

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

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

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
Запрос выполнен успешно.