Массовое редактирование сущностей
Запрос позволяет массово обновить сущности — цели, проекты или портфели проектов.
POST
https://api.tracker.yandex.net/v3/entities/<тип_сущности>/bulkchange/_update
Формат запроса
Перед выполнением запроса получите доступ к API.
Для пакетного изменения нескольких сущностей используйте HTTP-запрос с методом POST
. В теле запроса укажите параметры в формате JSON.
POST /v3/entities/<тип_сущности>/bulkchange/_update
Host: api.tracker.yandex.net
Authorization: OAuth <OAuth-токен>
X-Org-ID или X-Cloud-Org-ID: <идентификатор_организации>
{
"metaEntities":[ "<id_сущности_1>","<id_сущности_2>", ...],
"values":
{
"fields":
{
"<ключ_поля>":"<значение>",
...
},
"comment":"<комментарий>"
}
}
Заголовки
-
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.
Чтобы узнать идентификатор организации, перейдите на страницу Администрирование → Организации и скопируйте значение поля идентификатор.
-
Ресурс
Параметр | Описание | Тип данных |
---|---|---|
<тип_сущности> | Тип сущности:
|
Строка |
Параметры тела запроса
Обязательные параметры
Параметр | Описание | Тип данных |
---|---|---|
metaEntities | Список идентификаторов сущностей. | Массив строк |
values | Объект с настройками для пакетного обновления сущностей. | Объект |
Поля объекта values
Параметр | Описание | Тип данных |
---|---|---|
fields | Объект с парами «поле-значение». Подробнее читайте в разделе Дополнительные параметры сущности. | Объект |
comment | Комментарий. | Строка |
links | Массив объектов с настройками связей с другими сущностями. | Массив объектов |
Поля объектов массива links
Параметр |
Описание |
Тип данных |
relationship |
Тип связи. Для проектов и портфелей:
Для цели:
|
Строка |
entity |
Идентификатор связанной сущности. |
Строка |
Пример: Для нескольких проектов изменить статус, назначить наблюдателя и оставить комментарий
- Используется HTTP-метод POST.
- Статус проектов меняется на
Есть риски
.- Назначается наблюдатель.
- В комментарии проекта добавляется новая запись.
POST /v3/entities/project/bulkchange/_update HTTP/1.1 Host: api.tracker.yandex.net Authorization: OAuth <OAuth-токен> X-Org-ID или X-Cloud-Org-ID: <идентификатор_организации> { "metaEntities":[ "655f3be523db2132********","655f383923db2132********"], "values": { "fields": { "entityStatus":"at_risk", "followers":"agent007" }, "comment":"Проект в зоне риска" } }
Формат ответа
В случае успешного выполнения запроса API возвращает ответ с кодом 200 OK
.
Тело ответа содержит информацию о пакетном запросе в формате JSON.
{
"id": "6560c6f59b0b1e76********",
"self": "https://api.tracker.yandex.net/v3/bulkchange/6560c6f59b0b1e76********",
"createdBy": {
"self": "https://api.tracker.yandex.net/v3/users/11********",
"id": "11********",
"display": "Имя Фамилия",
"cloudUid": "ajevuhegoggf********",
"passportUid": 11********
},
"createdAt": "2023-11-24T15:53:25.122+0000",
"status": "CREATED",
"statusText": "Операция массового редактирования задач создана.",
"executionChunkPercent": 0,
"executionIssuePercent": 0
}
Параметры ответа
Параметр | Описание | Тип данных |
---|---|---|
id | Идентификатор пакетного запроса. | Строка |
self | Адрес ресурса API, который содержит информацию о пакетном запросе. | Строка |
createdBy | Блок с информацией о создателе пакетного запроса. | Объект |
createdAt | Дата создания сущности в формате YYYY-MM-DDThh:mm:ss.sss±hhmm . |
Строка |
status | Статус пакетного запроса. | Строка |
statusText | Расшифровка статуса пакетного запроса. | Строка |
Поля объекта createdBy
Параметр | Описание | Тип данных |
---|---|---|
self | Адрес ресурса API, который содержит информацию о пользователе. | Строка |
id | Идентификатор пользователя. | Строка |
display | Отображаемое имя пользователя. | Строка |
passportUid | Уникальный идентификатор аккаунта пользователя в организации Яндекс 360 для бизнеса и Яндекс ID. | Число |
cloudUid | Уникальный идентификатор пользователя в Yandex Cloud Organization. | Строка |
Если запрос не был успешно обработан, API возвращает ответ с кодом ошибки:
- 400
- Один или несколько параметров запроса имеют недопустимое значение.
- 401
- Пользователь не авторизован. Проверьте, были ли выполнены действия, описанные в разделе Доступ к API.
- 403
- У вас не хватает прав на выполнение этого действия. Наличие прав можно перепроверить в интерфейсе Трекера — для выполнения действия при помощи API и через интерфейс требуются одинаковые права.
- 412
- При редактировании объекта возник конфликт. Возможно, ошибка возникла из-за неправильно указанной версии изменений.
- 428
- Доступ к ресурсу отклонен. Проверьте, указаны ли все обязательные условия выполнения запроса.