Найти задачи

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

Yandex Cloud

Улучшена

tikhonovkv

Обновлена 4 октября 2024 г.

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

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

Если количество строк в ответе менее 10000, используйте постраничное отображение результатов.

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

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

Перед выполнением запроса получите доступ к API.

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

POST /v2/issues/_search?expand=transitions
Host: api.tracker.yandex.net
Authorization: OAuth <OAuth-токен>
X-Org-ID или X-Cloud-Org-ID: <идентификатор_организации>

{
   "filter": {
      "<имя_поля>": "<значение_в_поле>"
   },
   "order":"+<ключ_поля>"
}

Заголовки

Host

Адрес узла, предоставляющего API:
```
api.tracker.yandex.net
```
Authorization

OAuth-токен в формате OAuth <OAuth-токен>, например:
```
OAuth 0c4181a7c2cf4521964a72ff********
```
X-Org-ID или X-Cloud-Org-ID

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

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

Дополнительные параметры

Параметр	Описание	Тип данных
expand	Дополнительные поля, которые будут включены в ответ: `transitions` — переходы по жизненному циклу; `attachments` — вложения. `links` — связи.	Строка
perPage	Количество задач на странице ответа. Значение по умолчанию — 50. Дополнительные параметры показа ответа можно настроить с помощью механизма постраничного отображения.	Число

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

Для получения списка задач, укажите один из следующих параметров:

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

Примечание

Запрос не подразумевает комбинирование параметров.

При использовании комбинации двух параметров, в ответе будет возвращен результат по параметру с более высоким приоритетом.
Приоритеты параметров (в порядке убывания):

queue;
keys;
filter;
query.

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

Дополнительные параметры

Параметр	Описание	Формат
order	Направление и поле сортировки задач (только в комбинации с параметром `filter`). Значение указывается в формате `[+/-]<ключ_поля>`. Знак `+` или `-` обозначает направление сортировки.	Строка

Примечание

При использовании параметра query указывайте способ сортировки с помощью языка запросов.
Ответ на запрос с параметром queue сортируется по ключу задачи, а с параметром keys — по названиям задач в алфавитном порядке.

Пример 1: Запрос списка задач с помощью фильтра:

Используется HTTP-метод POST.

В ответе включено отображение вложений.

Ответ должен содержать только задачи из очереди «TREK», в которых не указан исполнитель.

Результаты отсортированы по статусу в возрастающем порядке.
POST /v2/issues/_search?expand=attachments HTTP/1.1
Host: api.tracker.yandex.net
Authorization: OAuth <OAuth-токен>
X-Org-ID или X-Cloud-Org-ID: <идентификатор_организации>

{
  "filter": {
    "queue": "TREK",
    "assignee": "Empty()"
  },
  "order":"+status"
}

Пример 2: Запрос списка задач с помощью языка запросов:

Используется HTTP-метод POST.

Ответ должен содержать только задачи из очереди «TREK», которые не являются эпиками.

Результаты отсортированы по дате обновления в убывающем порядке.
POST /v2/issues/_search?expand=attachments HTTP/1.1
Host: api.tracker.yandex.net
Authorization: OAuth <OAuth-токен>
X-Org-ID или X-Cloud-Org-ID: <идентификатор_организации>

{
  "query": "epic: notEmpty() Queue: TREK \"Sort by\": Updated DESC",
}

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

Запрос выполнен успешно

Запрос выполнен с ошибкой

В случае успешного выполнения запроса API возвращает ответ с кодом 200 OK.

Тело ответа содержит результаты в формате JSON.

[
    {
    "self": "https://api.tracker.yandex.net/v2/issues/TREK-9844",
    "id": "593cd211ef7e8a33********",
    "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": "593cd0acef7e8a33********",
        "key": "JUNE-2",
        "display": "Task"
        },
    "aliases": [
            "JUNE-3"
        ],

    "updatedBy": {
        "self": "https://api.tracker.yandex.net/v2/users/11********",
        "id": "11********",
        "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/53**",
        "id": "53**",
        "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/11********",
        "id": "11********",
        "display": "Иван Иванов"
        }
        ],
    "createdBy": {
        "self": "https://api.tracker.yandex.net/v2/users/11********",
        "id": "11********",
        "display": "Иван Иванов"
        },
    "votes": 0,
    "assignee": {
        "self": "https://api.tracker.yandex.net/v2/users/11********",
        "id": "11********",
        "display": "Иван Иванов"
        },
    "project": {
        "display": "Проект Стартрек",
        "id": "1",
        "self": "https://api.tracker.yandex.net/v2/projects/1"
    },
    "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	Объект с информацией об исполнителе задачи.	Объект
project	Объект с информацией о проекте задачи.	Объект
queue	Объект с информацией об очереди задачи.	Объект
updatedAt	Дата и время последнего обновления задачи.	Строка
status	Объект с информацией о статусе задачи.	Объект
previousStatus	Объект с информацией о предыдущем статусе задачи.	Объект
favorite	Признак избранной задачи: `true` — пользователь добавил задачу в избранное; `false` — задача не добавлена в избранное.	Логический

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

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

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

Параметр	Описание	Тип данных
self	Адрес ресурса API, который содержит информацию о пользователе.	Строка
id	Идентификатор пользователя.	Строка
display	Отображаемое имя пользователя.	Строка
passportUid	Уникальный идентификатор аккаунта пользователя в организации Яндекс 360 для бизнеса и Яндекс ID.	Число

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

Параметр	Описание	Тип данных
self	Адрес ресурса API, который содержит информацию о спринте.	Строка
id	Идентификатор спринта.	Строка
display	Отображаемое название спринта.	Строка

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

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

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

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

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

Параметр	Описание	Тип данных
self	Адрес ресурса API, который содержит информацию о пользователе.	Строка
id	Идентификатор пользователя.	Строка
display	Отображаемое имя пользователя.	Строка
passportUid	Уникальный идентификатор аккаунта пользователя в организации Яндекс 360 для бизнеса и Яндекс ID.	Число

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

Параметр	Описание	Тип данных
self	Адрес ресурса API, который содержит информацию о пользователе.	Строка
id	Идентификатор пользователя.	Строка
display	Отображаемое имя пользователя.	Строка
passportUid	Уникальный идентификатор аккаунта пользователя в организации Яндекс 360 для бизнеса и Яндекс ID.	Число

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

Параметр	Описание	Тип данных
self	Адрес ресурса API, который содержит информацию о пользователе.	Строка
id	Идентификатор пользователя.	Строка
display	Отображаемое имя пользователя.	Строка
passportUid	Уникальный идентификатор аккаунта пользователя в организации Яндекс 360 для бизнеса и Яндекс ID.	Число

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

Параметр	Описание	Тип данных
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 (необязательный параметр)

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

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

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

Ответ на запрос с прокруткой

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

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

Ответ содержит заголовки:

Link

Ссылка для перехода на следующую страницу результатов поиска. Ссылку можно использовать только для перехода к следующей и к первой страницам.
X-Scroll-Id

Идентификатор страницы.
X-Scroll-Token

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

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

Пример

Рассмотрим получение результатов поиска с использованием прокрутки на примере: найти все задачи, которые назначены на сотрудника.

Условия запроса:

Используется HTTP-метод GET.
Ключ очереди — «TREK».
Исполнитель задачи — <логин_пользователя>.
Результаты поиска должны быть отсортированы.

Последовательность выполнения серии запросов:

Создайте первый запрос серии с параметрами:
- scrollType=sorted
- perScroll=100
- scrollTTLMillis=10000
Пример:
```
POST /v2/issues/_search?scrollType=sorted&perScroll=100&scrollTTLMillis=10000
Host: api.tracker.yandex.net
Authorization: OAuth <OAuth-токен>
X-Org-ID или X-Cloud-Org-ID: <идентификатор_организации>

{
  "filter": {
    "queue": "TREK",
    "assignee": "<логин_пользователя>"
  }
}
```
Ответ на запрос будет содержать список задач и заголовки:
- Link — ссылки на первую и следующую страницы результатов:
```
Link: <https://api.tracker.yandex.net/v2/issues/_search?expand=&embed=&fields=&staleOk=false&scrollType=sorted&scrollTTLMillis=10000&perScroll=2000>; rel="first"
Link: <https://api.tracker.yandex.net/v2/issues/_search?expand=&embed=&fields=&staleOk=false&scrollTTLMillis=10000&scrollId=6554d4cbbda0de18********&scrollToken=dummy-token-you-dont-have-to-specify-it>; rel="next"
```
  Используйте ссылку из заголовка с параметром rel="next" для получения следующей страницы результатов.
- X-Total-Count — общее количество задач в выдаче.
Если запрошенная страница не является последней, также возвращаются заголовки:
- X-Scroll-Id. Значение используется в параметре scrollId для получения следующей страницы результатов.
- X-Scroll-Token. Значение не используется в текущей версии API v2.
Создайте второй запрос серии с параметрами scrollId и scrollToken, полученными на предыдущем шаге.

Пример:
```
POST /v2/issues/_search?scrollId=cXVlcnlU<...>&scrollTTLMillis=10000
Host: api.tracker.yandex.net
Authorization: OAuth <OAuth-токен>
X-Org-ID или X-Cloud-Org-ID: <идентификатор_организации>

{
  "filter": {
    "queue": "TREK",
    "assignee": "<логин_пользователя>"
  }
}
```
На запрос будет получен ответ со следующей страницей списка задач и очередными значениями X-Scroll-Id и X-Scroll-Token, если страница не окажется последней.
Продолжайте отправлять запросы на получение следующей страницы результатов до тех пор, пока не получите все задачи из выдачи.

Найти задачи

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

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

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

Параметры запроса с прокруткойПараметры запроса с прокруткой

Ответ на запрос с прокруткойОтвет на запрос с прокруткой

ПримерПример

Была ли статья полезна?

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

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

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

Параметры запроса с прокруткой

Ответ на запрос с прокруткой

Пример