Найти задачи

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

Запрос позволяет получить список задач, удовлетворяющих заданному критерию. Если количество задач в ответе более 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": "ключ очереди"
}

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

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