Найти задачи

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

POST

https://api.tracker.yandex.net/v3/issues/_search?expand=transitions

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

  1. Постраничное отображение — для запросов с параметрами filter, query или keys при количестве результатов менее 10000.
  2. Относительная пагинация — для запросов с параметром queue.
  3. Механизм прокрутки — для запросов с большим количеством результатов (более 10000).

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

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

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

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

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

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

  • Authorization: токен для авторизации в одном из форматов:

    • OAuth <OAuth-токен> при авторизации по протоколу OAuth 2.0. Читать подробнее

    • Bearer <IAM-токен> при авторизации с помощью IAM-токена — если к Трекеру привязана организация Yandex Cloud Organization. Читать подробнее

  • X-Org-ID или X-Cloud-Org-ID: идентификатор организации.

    • Используйте заголовок X-Org-ID, если к Трекеру привязана организация Яндекс 360 для бизнеса.

    • Используйте заголовок X-Cloud-Org-ID, если к Трекеру привязана организация Yandex Cloud Organization.

    Чтобы узнать идентификатор организации, перейдите на страницу Администрирование → Организации и скопируйте значение поля идентификатор.

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

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

Параметр

Описание

Тип данных

expand

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

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

Строка

perPage

Количество задач на странице ответа. Значение по умолчанию — 50. При использовании параметра queue поддерживается только относительная пагинация. Для других параметров (filter, query, keys) используется постраничное отображение.

Число

page

Номер страницы ответа при постраничном отображении.

Число

id

Идентификатор страницы ответа при относительной пагинации.

Число

scrollType
perScroll
scrollTTLMillis
scrollId

Параметры отображения ответа при использовании механизма прокрутки.

Строка
Число
Число
Число
Параметры тела запроса

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

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

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

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

  1. queue;
  2. keys;
  3. filter;
  4. query.

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

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

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

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

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

  • Используется HTTP-метод POST.
  • В ответе включено отображение вложений.
  • Ответ должен содержать только задачи из очереди «TREK», в которых не указан исполнитель.
  • Результаты отсортированы по статусу в возрастающем порядке.
POST /v3/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 /v3/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/v3/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/v3/issues/JUNE-2",
        "id": "593cd0acef7e8a33********",
        "key": "JUNE-2",
        "display": "Task"
        },
    "aliases": [
            "JUNE-3"
        ],

    "updatedBy": {
        "self": "https://api.tracker.yandex.net/v3/users/11********",
        "id": "11********",
        "display": "Имя Фамилия",
        "cloudUid": "ajeppa7dgp53********",
        "passportUid": 11********
        },
    "description": "<#<html><head></head><body><div>test</div><div> </div><div> </div> </body></html>#>",
    "sprint": [
        {
            "self": "https://api.tracker.yandex.net/v3/sprints/53**",
            "id": "53**",
            "display": "Sprint 1"
        }
    ],
    "type": {
        "self": "https://api.tracker.yandex.net/v3/issuetypes/2",
        "id": "2",
        "key": "task",
        "display": "Задача"
        },
    "priority": {
        "self": "https://api.tracker.yandex.net/v3/priorities/2",
        "id": "2",
        "key": "normal",
        "display": "Средний"
        },

    "createdAt": "2017-06-11T05:16:01.339+0000",
    "followers": [
        {
        "self": "https://api.tracker.yandex.net/v3/users/11********",
        "id": "11********",
        "display": "Имя Фамилия",
        "cloudUid": "ajeppa7dgp53********",
        "passportUid": 11********
        }
        ],
    "createdBy": {
        "self": "https://api.tracker.yandex.net/v3/users/11********",
        "id": "11********",
        "display": "Имя Фамилия",
        "cloudUid": "ajeppa7dgp53********",
        "passportUid": 11********
        },
    "votes": 0,
    "assignee": {
        "self": "https://api.tracker.yandex.net/v3/users/11********",
        "id": "11********",
        "display": "Имя Фамилия",
        "cloudUid": "ajeppa7dgp53********",
        "passportUid": 11********
        },
    "project": {
        "primary": {
            "self": "https://api.tracker.yandex.net/v3/projects/1",
            "id": "1",
            "display": "New project"
        },
        "secondary": []
    },
    "queue": {
        "self": "https://api.tracker.yandex.net/v3/queues/TREK",
        "id": "111",
        "key": "TREK",
        "display": "My queue"
        },
    "updatedAt": "2017-07-18T13:33:44.291+0000",
    "status": {
        "self": "https://api.tracker.yandex.net/v3/statuses/1",
        "id": "1",
        "key": "open",
        "display": "Открыт"
        },
    "previousStatus": {
        "self": "https://api.tracker.yandex.net/v3/statuses/2",
        "id": "2",
        "key": "resolved",
        "display": "Решен"
        },
    "favorite": false
    },
    {...}
]
Параметры ответа

В таблице перечислены часто используемые параметры задачи. Полный список поддерживаемых параметров можно найти на странице https://tracker.yandex.ru/admin/fields.

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

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

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

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

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

Поля объектов массива 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. Число
cloudUid Уникальный идентификатор пользователя в Yandex Cloud Organization. Строка

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

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

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

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

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

Параметр Описание Тип данных
primary Основной проект задачи Объект
secondary Список дополнительных проектов задачи Массив объектов

Если в адресе запроса указана версия API v2, объект project содержит информацию только об основном проекте.

Поля объекта, содержащего данные проекта

Параметры primary и secondary содержат объекты со следующими полями:

Параметр Описание Тип данных
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
У вас не хватает прав на выполнение этого действия. Наличие прав можно перепроверить в интерфейсе Трекера — для выполнения действия при помощи API и через интерфейс требуются одинаковые права.
404
Запрошенный объект не был найден. Возможно, вы указали неверное значение идентификатора или ключа объекта.

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

Постраничное отображение используется для запросов с параметрами filter, query или keys при количестве результатов менее 10000.

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

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

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

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

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

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

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

Заголовки ответа

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

  • X-Total-Pages

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

  • X-Total-Count

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

Пример запроса с постраничным отображением

Найти задачи с помощью фильтра и отобразить результаты постранично:

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

{
  "filter": {
    "assignee": "<user_login>",
    "status": "open"
  }
}

Относительная пагинация

Для запросов с параметром queue используется относительная пагинация, постраничное отображение с параметром page не поддерживается.

При использовании относительной пагинации следующая страница определяется через заголовок Link в ответе.

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

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

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

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

    Идентификатор страницы из заголовка Link.

Заголовки ответа

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

  • Link

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

Пример запроса с относительной пагинацией

  1. Первый запрос для получения задач очереди:

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

{
  "queue": "TREK"
}

    В заголовке Link ответа будет содержаться ссылка для получения следующей страницы:

    Link: <api.tracker.yandex.net/v3/issues/_search?id=5f2ad1314033c53616b50cd9&perPage=10>; rel="next"

  2. Запрос следующей страницы с использованием параметра id из заголовка Link:

    POST /v3/issues/_search?id=5f2ad1314033c53616b50cd9&perPage=10
Host: api.tracker.yandex.net
Authorization: OAuth <OAuth-токен>
X-Org-ID или X-Cloud-Org-ID: <идентификатор_организации>

{
  "queue": "TREK"
}

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

Если ответ на запрос поиска задач содержит более 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-метод POST.
  • Ключ очереди — «TREK».
  • Исполнитель задачи — <логин_пользователя>.
  • Результаты поиска должны быть отсортированы.

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

  1. Создайте первый запрос серии с параметрами:

    • scrollType=sorted
    • perScroll=100
    • scrollTTLMillis=10000

    Пример:

    POST /v3/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": "username"
  }
}

    Ответ на запрос будет содержать список задач и заголовки:

    • Link — ссылки на первую и следующую страницы результатов:

      Link: <api.tracker.yandex.net/v3/issues/_search?expand=&embed=&fields=&staleOk=false&scrollType=sorted&scrollTTLMillis=10000&perScroll=2000>; rel="first"
Link: <api.tracker.yandex.net/v3/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 v3.

  2. Создайте второй запрос серии с параметрами scrollId и scrollToken, полученными на предыдущем шаге.

    Пример:

    POST /v3/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": "username"
  }
}

    На запрос будет получен ответ со следующей страницей списка задач и очередными значениями X-Scroll-Id и X-Scroll-Token, если страница не окажется последней.

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

Предыдущая
Узнать количество задач
Следующая
Сформировать подсказки (suggest) при поиске задач