Найти задачи
Запрос позволяет получить список задач, удовлетворяющих заданному критерию.
Если количество строк в ответе от 50 до 10000, используйте постраничное отображение результатов.
Если количество строк в ответе более 10000, используйте механизм прокрутки результатов.
Формат запроса
Перед выполнением запроса получите доступ к API.
Для поиска задач используйте HTTP-запрос с методом POST
. Тело запроса содержит критерии для поиска.
POST /v2/issues/_search
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 | Дополнительные поля, которые будут включены в ответ:
|
Строка |
perPage | Количество задач на странице ответа. Значение по умолчанию — 50. Дополнительные параметры показа ответа можно настроить с помощью механизма постраничного отображения. | Число |
Дополнительные параметры
Параметр | Описание | Формат |
---|---|---|
filter | Параметры фильтрации задач. В параметре можно указать название любого поля и значение, по которому будет производиться фильтрация. | Объект |
query | Фильтр на языке запросов. | Строка |
expand | Дополнительные поля, которые будут включены в ответ:
|
Строка |
keys | Список ключей задач. Данный параметр не используется вместе с параметрами filter или query . При совместной передаче этих параметров, поиск будет производиться только по keys . |
Строка |
queue | Очередь. Данный параметр не используется вместе с параметрами filter или query . При совместной передаче этих параметров, поиск будет производиться только по queue . |
Строка |
Параметры queue
и keys
не используются одновременно с параметрами filter
или query
. При их совместной передаче ответ будет содержать код 400 с сообщением Вы можете использовать только ключи, очередь или поисковый запрос.
Запрос списка задач с указанием дополнительных параметров фильтрации:
- Используется HTTP-метод POST.
- Включено постраничное отображение, каждая страница содержит по две записи.
- В ответе включено отображение приложений.
- Ответ должен содержать только задачи из очереди
JUNE, в которых не указан исполнитель.POST /v2/issues/_search?scrollType=sorted&perScroll=2&expand=attachments HTTP/1.1 Host: https://api.tracker.yandex.net Authorization: OAuth <OAuth-токен> X-Org-ID: <идентификатор организации> { "filter": { "queue": "JUNE", "assignee": "Empty()" } }
Формат ответа
В случае успешного выполнения запроса API возвращает ответ с кодом 200 OK
.
Тело ответа содержит результаты в формате JSON.
[
{
"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> </div><div> </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 | Признак избранной задачи:
|
Логический |
Поля объекта parent
Параметр | Описание | Тип данных |
---|---|---|
self | Адрес ресурса API, который содержит информацию о задаче. | Строка |
id | Идентификатор задачи. | Строка |
key | Ключ задачи. | Строка |
display | Отображаемое название задачи. | Строка |
Поля объекта updatedBy
Параметр | Описание | Тип данных |
---|---|---|
self | Адрес ресурса API, который содержит информацию о пользователе. | Строка |
id | Идентификатор пользователя. | Строка |
display | Отображаемое имя пользователя. | Строка |
Поля объектов массива sprint
Параметр | Описание | Тип данных |
---|---|---|
self | Адрес ресурса API, который содержит информацию о спринте. | Строка |
id | Идентификатор спринта. | Строка |
display | Отображаемое название спринта. | Строка |
Поля объекта type
Параметр | Описание | Тип данных |
---|---|---|
self | Адрес ресурса API, который содержит информацию о типе задаче. | Строка |
id | Идентификатор типа задачи. | Строка |
key | Ключ типа задачи. | Строка |
display | Отображаемое название типа задачи. | Строка |
Поля объекта priority
Параметр | Описание | Тип данных |
---|---|---|
self | Адрес ресурса API, который содержит информацию о приоритете. | Строка |
id | Идентификатор приоритета. | Строка |
key | Ключ приоритета. | Строка |
display | Отображаемое название приоритета. | Строка |
Поля объектов массива followers
Параметр | Описание | Тип данных |
---|---|---|
self | Адрес ресурса API, который содержит информацию о пользователе. | Строка |
id | Идентификатор пользователя. | Строка |
display | Отображаемое имя пользователя. | Строка |
Поля объекта createdBy
Параметр | Описание | Тип данных |
---|---|---|
self | Адрес ресурса API, который содержит информацию о пользователе. | Строка |
id | Идентификатор пользователя. | Строка |
display | Отображаемое имя пользователя. | Строка |
Поля объекта assignee
Параметр | Описание | Тип данных |
---|---|---|
self | Адрес ресурса API, который содержит информацию о пользователе. | Строка |
id | Идентификатор пользователя. | Строка |
display | Отображаемое имя пользователя. | Строка |
Поля объекта queue
Параметр | Описание | Тип данных |
---|---|---|
self | Адрес ресурса API, который содержит информацию об очереди. | Строка |
id | Идентификатор очереди. | Строка |
key | Ключ очереди. | Строка |
display | Отображаемое название очереди. | Строка |
Поля объекта status
Параметр | Описание | Тип данных |
---|---|---|
self | Адрес ресурса API, который содержит информацию о статусе. | Строка |
id | Идентификатор статуса. | Строка |
key | Ключ статуса. | Строка |
display | Отображаемое название статуса. | Строка |
Поля объекта previousStatus
Параметр | Описание | Тип данных |
---|---|---|
self | Адрес ресурса API, который содержит информацию о статусе. | Строка |
id | Идентификатор статуса. | Строка |
key | Ключ статуса. | Строка |
display | Отображаемое название статуса. | Строка |
Если запрос не был успешно обработан, API возвращает ответ с кодом ошибки:
- 400
- Один или несколько параметров запроса имеют недопустимое значение.
- 401
- Пользователь не авторизован. Проверьте, были ли выполнены действия, описанные в разделе Доступ к API.
- 403
- У вас не хватает прав на выполнение этого действия. Наличие прав можно перепроверить в интерфейсе Tracker — для выполнения действия при помощи API и через интерфейс требуются одинаковые права.
- 404
- Запрошенный объект не был найден. Возможно, вы указали неверное значение идентификатора или ключа объекта.
Прокрутка результатов поиска
Если ответ на запрос поиска задач содержит более 10000 строк, рекомендуем использовать механизм прокрутки результатов.
При использовании механизма прокрутки в ответ на запрос возвращается страница с результатами поиска и идентификатором для получения следующей страницы.
Результаты поиска можно отобразить в отсортированном виде или в произвольном порядке. Чтобы уменьшить количество затрачиваемых ресурсов при поиске большого количества задач, используйте механизм прокрутки без сортировки.
Примечание
Прокрутка результатов поиска требует больше ресурсов по сравнению с постраничным отображением результатов.
Параметры запроса с прокруткой
-
scrollType
Тип прокрутки. Допустимые значения:
sorted
— используется указанная в запросе сортировка;unsorted
— сортировка не используется.
Данный параметр используется только в первом из серии запросов прокрутки.
Данный параметр не используется совместно с параметрами поиска
keys
илиqueue
. При использовании прокрутки и этих параметров ответ будет содержать код 400 и сообщениеПрокрутка результатов не поддерживается
. Чтобы найти задачи очереди, используйте параметрыfilter
илиquery
. -
perScroll
Максимальное количество задач в ответе. Значение по умолчанию — 100, максимально допустимое значение — 1000.
Данный параметр используется только в первом из серии запросов прокрутки.
-
scrollTTLMillis (необязательный параметр)
Время жизни контекста прокрутки и токена
scrollToken
в миллисекундах. Значение по умолчанию — 5000, максимально допустимое значение — 60000. -
scrollId
Идентификатор страницы.
Данный параметр указывается во втором и следующих запросах серии прокрутки. Значение параметра должно быть получено из заголовка
X-Scroll-Id
, который возвращается в ответе на предыдущий запрос серии. -
scrollToken
Токен, удостоверяющий принадлежность запроса текущему пользователю.
Данный параметр указывается во втором и следующих запросах серии прокрутки. Значение параметра должно быть получено из заголовка
X-Scroll-Token
, который возвращается в ответе на предыдущий запрос серии.Время жизни токена соответствует значению, указанному в параметре scrollTTLMillis. Если время жизни токена истекло, ответ будет содержать код 403 и сообщение
Просроченная подпись
.
Ответ на запрос с прокруткой
При использовании прокрутки создается слепок результатов поиска. Переключение между страницами результатов осуществляется в рамках данного слепка. Таким образом, если какая-либо задача будет изменена и перестанет отвечать требованиям поискового запроса, это не повлияет на отображение задачи в слепке результатов поиска.
Слепок результатов поиска сохраняется, пока не будут просмотрены все страницы. Если вы не хотите загружать все результаты поиска, освободите занятые ресурсы с помощью запроса Освободить ресурсы просмотра прокрутки.
Ответ содержит заголовки:
-
Link
Ссылка для перехода на следующую страницу результатов поиска. Ссылку можно использовать только для перехода к следующей и к первой страницам.
-
X-Scroll-Id
Идентификатор страницы.
-
X-Scroll-Token
Токен, удостоверяющий принадлежность запроса текущему пользователю.
-
X-Total-Count
Общее число записей в ответе.
Пример
Рассмотрим получение результатов поиска с использованием прокрутки на примере: найти все задачи, которые назначены на сотрудника.
Условия запроса:
- Используется HTTP-метод
GET
. - Ключ очереди —
TREK
. - Исполнитель задачи — <user_login>.
- Результаты поиска должны быть отсортированы.
Последовательность выполнения серии запросов:
-
Создайте первый запрос серии с параметрами:
scrollType=sorted
perScroll=100
scrollTTLMillis=10000
Пример:
POST /v2/issues/_search?scrollType=sorted&perScroll=100&scrollTTLMillis=10000 Host: https://api.tracker.yandex.net Authorization: OAuth <OAuth-токен> X-Org-ID: <идентификатор организации> { "filter": { "queue": "TREK", "assignee": "<user_login>" } }
Ответ на запрос будет содержать список задач и заголовки:
Link
;X-Total-Count
.
Если прокрутка еще не закончена, также возвращаются заголовки:
X-Scroll-Id
. Значение используется в параметреscrollId
для получения следующей страницы результатов.X-Scroll-Token
. Значение используется в параметреscrollToken
для получения следующей страницы результатов.
-
Создайте второй запрос серии с параметрами
scrollId
иscrollToken
, полученными на предыдущем шаге.Пример:
POST /v2/issues/_search?scrollId=cXVlcnlU<...>&scrollToken=08e06389<...>&scrollTTLMillis=10000 Host: https://api.tracker.yandex.net Authorization: OAuth <OAuth-токен> X-Org-ID: <идентификатор организации> { "filter": { "queue": "TREK", "assignee": "<user_login>" } }
На запрос будет получен ответ со следующей страницей списка задач и очередными значениями
X-Scroll-Id
иX-Scroll-Token
, если прокрутка еще не закончена. -
Продолжайте отправлять запросы до тех пор, пока не получите все задачи.