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

Запрос позволяет массово обновить сущности — цели, проекты или портфели проектов.

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.

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

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

Обязательные параметры

Параметр Описание Тип данных
metaEntities Список идентификаторов сущностей. Массив строк
values Объект с настройками для пакетного обновления сущностей. Объект

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

Параметр Описание Тип данных
fields Объект с парами «поле-значение». Подробнее читайте в разделе Дополнительные параметры сущности. Объект
comment Комментарий. Строка
links Массив объектов с настройками связей с другими сущностями. Массив объектов

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

Параметр

Описание

Тип данных

relationship

Тип связи. Для проектов и портфелей:

  • depends on — текущая сущность зависит от связанной
  • is dependent by — текущая сущность блокирует связанную
  • works towards — связь проекта с целью

Для цели:

  • parent entity — родительская цель
  • child entity — подцель
  • depends on — текущая цель зависит от связанной
  • is dependent by — текущая цель блокирует связанную
  • is supported by — связь с проектом

Строка

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
Доступ к ресурсу отклонен. Проверьте, указаны ли все обязательные условия выполнения запроса.