Получить список сущностей

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

POST

https://api.tracker.yandex.net/v3/entities/<тип_сущности>/_search?fields=entityStatus

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

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

Чтобы получить список сущностей, используйте HTTP-запрос с методом POST. В теле запроса укажите параметры в формате JSON.

POST /v3/entities/<тип_сущности>/_search?fields=entityStatus
Host: api.tracker.yandex.net
Authorization: OAuth <OAuth-токен>
X-Org-ID или X-Cloud-Org-ID: <идентификатор_организации>

{
   "filter": 
   {
      "author": "<логин_пользователя>"
   }   
}

Заголовки

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.
Чтобы узнать идентификатор организации, перейдите на страницу Администрирование → Организации и скопируйте значение поля идентификатор.

Ресурс

Параметр	Описание	Тип данных
<тип_сущности>	Тип сущности: project — проект; portfolio — портфель; goal — цель	Строка

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

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

Параметр	Описание	Тип данных
fields	Дополнительные поля, которые будут включены в ответ.	Строка
perPage	Количество задач на странице ответа. Значение по умолчанию — 50.	Число
page	Страница выдачи. Значение по умолчанию — 1.	Число

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

Тело запроса содержит информацию, необходимую для поиска сущностей:

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

Параметр	Описание	Тип данных
input	Подстрока в названии сущности.	Строка
filter	Параметры фильтрации задач. В параметре можно указать ключ любого поля и значение, по которому будет производиться фильтрация.	Объект
orderBy	Параметры сортировки задач. В параметре можно указать ключ любого поля, по которому будет производиться сортировка.	Строка
orderAsc	Направление сортировки.	Логический
rootOnly	Выводить только не вложенные сущности.	Логический

Ключи полей и ключи значений (например, статусов) сущностей не всегда совпадают с аналогичными ключами задач.

Пример 1: Получить список сущностей с помощью фильтра с расширенным списком полей в выдаче

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

Ответ должен содержать только взятые в работу проекты с непустым списком наблюдателей.

В ответе включено отображение полей Статус, Автор и Наблюдатели.
POST /v3/entities/project/_search?fields=entityStatus,author,followers HTTP/1.1
Host: api.tracker.yandex.net
Authorization: OAuth <OAuth-токен>
X-Org-ID или X-Cloud-Org-ID: <идентификатор_организации>

{
  "filter": {
    "followers": "notEmpty()",
    "entityStatus": "in_progress"
  }
}

Пример 2: Получить сортированный список всех сущностей

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

Ответ должен содержать все портфели, отсортированные по статусам.

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

В ответе включено отображение полей Статус и Автор.
POST /v3/entities/project/_search?fields=entityStatus,author HTTP/1.1
Host: api.tracker.yandex.net
Authorization: OAuth <OAuth-токен>
X-Org-ID или X-Cloud-Org-ID: <идентификатор_организации>

{
  "orderBy": "entityStatus", 
  "orderAsc":true
}

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

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

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

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

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

{
   "hits": 8,
   "pages": 1,
   "values": [
     {
         "self": "https://api.tracker.yandex.net/v3/entities/project/655f8ce5d6a39833********",
         "id": "655f8ce5d6a39833********",
         "version": 7,
         "shortId": 8,
         "entityType": "project",
         "createdBy": { "self": "https://api.tracker.yandex.net/v3/users/11********", "id": "11********", "display": "Имя Фамилия", "cloudUid": "ajevuhegoggf********", "passportUid": 11******** },
         "createdAt": "2023-11-23T17:33:25.427+0000",
         "updatedAt": "2023-11-24T12:21:43.838+0000",
         "fields": {
             "entityStatus": "in_progress",
             "followers": [{ "self": "https://api.tracker.yandex.net/v3/users/11********", "id": "11********", "display": "Имя Фамилия", "cloudUid": "ajeprm0fjnql********", "passportUid": 11******** }]
         }
     },
     {
         "self": "https://api.tracker.yandex.net/v3/entities/project/655f3815a834c763********",
         "id": "655f3815a834c763********",
         "version": 4,
         "shortId": 3,
         "entityType": "project",
         "createdBy": { "self": "https://api.tracker.yandex.net/v3/users/11********", "id": "11********", "display": "Имя Фамилия", "cloudUid": "ajevuhegoggf********", "passportUid": 11******** },
         "createdAt": "2023-11-23T11:31:33.874+0000",
         "updatedAt": "2023-11-23T21:52:10.863+0000",
         "fields": {
             "entityStatus": "draft",
             "followers": [{ "self": "https://api.tracker.yandex.net/v3/users/11********", "id": "11********", "display": "Имя Фамилия", "cloudUid": "ajeprm0fjnql********", "passportUid": 11******** }]
         }
     }
   ],
   "orderBy": "entityStatus"
}

Параметры ответа

Параметр	Описание	Тип данных
hits	Количество результатов в выдаче.	Число
pages	Количество страниц в выдаче.	Число
values	Результаты. Объекты сущностей.	Массив объектов

Поля объектов сущностей

Параметр	Описание	Тип данных
self	Адрес ресурса API, который содержит информацию о сущности	Строка
id	Идентификатор сущности	Строка
version	Версия сущности. Каждое изменение параметров увеличивает номер версии. Редактирование сущности будет заблокировано, если версия достигнет предельного значения: для роботов `10100`, для пользователей `11100`	Число
shortId	Числовой идентификатор сущности	Число
entityType	Тип сущности	Строка
createdBy	Блок с информацией о создателе сущности	Объект
createdAt	Дата создания сущности в формате `YYYY-MM-DDThh:mm:ss.sss±hhmm`	Строка
updatedAt	Дата последнего обновления сущности в формате `YYYY-MM-DDThh:mm:ss.sss±hhmm`	Строка
fields	Блок с дополнительными полями сущности	Объект

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

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

Если запрос не был успешно обработан, API возвращает ответ с кодом ошибки:

400: Один или несколько параметров запроса имеют недопустимое значение.

401: Пользователь не авторизован. Проверьте, были ли выполнены действия, описанные в разделе Доступ к API.

403: У вас не хватает прав на выполнение этого действия. Наличие прав можно перепроверить в интерфейсе Трекера — для выполнения действия при помощи API и через интерфейс требуются одинаковые права.

404: Запрошенный объект не был найден. Возможно, вы указали неверное значение идентификатора или ключа объекта.

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

Удалить сущность

Массовое редактирование сущностей