## Формат запроса {#query}
Перед выполнением запроса [получите доступ к API](https://yandex.ru/support/tracker/ru/api/access.md).
Для пакетного изменения нескольких сущностей используйте HTTP-запрос с методом `POST`. В теле запроса укажите параметры в формате JSON.
```json translate=no
POST /v3/entities/{тип_сущности}/bulkchange/_update
Host: api.tracker.yandex.net
Authorization: OAuth API_TOKEN
Content-Type: application/json
X-Org-ID или X-Cloud-Org-ID: ИДЕНТИФИКАТОР_ОРГАНИЗАЦИИ
{
"metaEntities":[ "ID_СУЩНОСТИ_1","ID_СУЩНОСТИ_2", ...],
"values":
{
"fields":
{
"КЛЮЧ_ПОЛЯ":"ЗНАЧЕНИЕ",
...
},
"comment":"КОММЕНТАРИЙ"
}
}
```
{% cut "Заголовки" %}
* `Host`: адрес узла, предоставляющего API.
*
`Authorization`: токен для авторизации в одном из форматов:
- `OAuth OAUTH_TOKEN` при авторизации по протоколу OAuth 2.0. [Читать подробнее](https://yandex.ru/support/tracker/ru/api/access.md#about_OAuth)
- `Bearer IAM_TOKEN` при авторизации с помощью IAM-токена — если к Трекеру привязана организация Yandex Identity Hub. [Читать подробнее](https://yandex.ru/support/tracker/ru/api/access.md#iam-token)
*
`Content-Type`: формат тела запроса. Должен иметь значение `application/json`.
*
`X-Org-ID` или `X-Cloud-Org-ID`: идентификатор организации.
- если к Трекеру привязана организация Яндекс 360 для бизнеса, используйте заголовок `X-Org-ID`,
- если к Трекеру привязана организация Yandex Identity Hub, используйте заголовок `X-Cloud-Org-ID`.
Чтобы узнать идентификатор организации, перейдите на страницу **Администрирование** → [**Организации**](https://tracker.yandex.ru/admin/orgs) и скопируйте значение поля **идентификатор**.
{% endcut %}
{% cut "Ресурс" %}
Параметр | Описание | Тип данных
-------- | -------- | ----------
`тип_сущности` | Тип сущности:
project — проект;
portfolio — портфель;
goal — цель
| Строка
{% endcut %}
{% cut "Параметры тела запроса" %}
**Обязательные параметры**
Параметр | Описание | Тип данных
-------- | -------- | ----------
metaEntities | Список идентификаторов сущностей. | Массив строк
values | Объект с настройками для пакетного обновления сущностей. | Объект
**Поля объекта** `values`
Параметр | Описание | Тип данных
-------- | -------- | ----------
fields | Объект с парами «поле-значение». Подробнее читайте в разделе [Дополнительные параметры сущности](about-entities.md#query-params). | Объект
comment | Комментарий. | Строка
links | Массив объектов с настройками связей с другими сущностями. | Массив объектов
**Поля объектов массива** `links`
#|
|| Параметр | Описание | Тип данных ||
|| relationship |
{% include [links](../_includes/entity-links.md) %} |
Строка
||
|| entity | Идентификатор связанной сущности. | Строка ||
|#
{% endcut %}
> Пример: Для нескольких проектов изменить статус, назначить наблюдателя и оставить комментарий
>
> - Используется HTTP-метод POST.
> - Статус проектов меняется на `Есть риски`.
> - Назначается наблюдатель.
> - В комментарии проекта добавляется новая запись.
>
> ```json translate=no
> POST /v3/entities/project/bulkchange/_update HTTP/1.1
> Host: api.tracker.yandex.net
> Authorization: OAuth API_TOKEN
> Content-Type: application/json
> X-Org-ID: 1234******
>
> {
> "metaEntities":[ "655f3be523db2132********","655f383923db2132********"],
> "values":
> {
> "fields":
> {
> "entityStatus":"at_risk",
> "followers":"agent007"
> },
> "comment":"Проект в зоне риска"
> }
> }
> ```
## Формат ответа {#answer}
{% list tabs %}
- Запрос выполнен успешно
В случае успешного выполнения запроса API возвращает ответ с кодом `200 OK`.
Тело ответа содержит информацию о пакетном запросе в формате JSON.
```json translate=no
{
"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
}
```
{% cut "Параметры ответа" %}
Параметр | Описание | Тип данных
-------- | -------- | ----------
id | Идентификатор пакетного запроса. | Строка
self | Адрес ресурса API, который содержит информацию о пакетном запросе. | Строка
createdBy | Блок с информацией о создателе пакетного запроса. | Объект
createdAt | Дата создания сущности в формате `YYYY-MM-DDThh:mm:ss.sss±hhmm`. | Строка
status | Статус пакетного запроса. | Строка
statusText | Расшифровка статуса пакетного запроса. | Строка
**Поля объекта** `createdBy`
Параметр | Описание | Тип данных
----- | ----- | -----
self | Адрес ресурса API, который содержит информацию о пользователе. | Строка
id | Идентификатор пользователя. | Строка
display | Отображаемое имя пользователя. | Строка
passportUid | Уникальный идентификатор аккаунта пользователя в организации Яндекс 360 для бизнеса и Яндекс ID. | Число
cloudUid | Уникальный идентификатор пользователя в Yandex Identity Hub. | Строка
{% endcut %}
- Запрос выполнен с ошибкой
Если запрос не был успешно обработан, API возвращает ответ с кодом ошибки:
400
: Один или несколько параметров запроса имеют недопустимое значение.
401
: Пользователь не авторизован. Проверьте, были ли выполнены действия, описанные в разделе [Доступ к API](https://yandex.ru/support/tracker/ru/api/access.md).
403
: У вас не хватает прав на выполнение этого действия. Наличие прав можно перепроверить в интерфейсе Трекера — для выполнения действия при помощи API и через интерфейс требуются одинаковые права.
412
: При редактировании объекта возник конфликт. Возможно, ошибка возникла из-за неправильно указанной версии изменений.
428
: Доступ к ресурсу отклонен. Проверьте, указаны ли все обязательные условия выполнения запроса.
{% endlist %}
[*portfolio]: Портфель — это инструмент для объединения проектов и других портфелей по продукту, отделу или другому признаку.
Когда у вас несколько параллельных проектов, портфель позволяет взглянуть на них с высоты: как распределены ресурсы, где сроки подходят к концу.
[*project]: Проект — это набор задач из разных очередей, в которых работают над общим результатом. Это может быть запуск мобильного приложения или редизайн главной страницы сайта.
Проект помогает отслеживать: сколько задач сделано, сколько осталось, укладывается ли команда в сроки.
[*goal]: Цель — это стратегия развития или желаемый итог работы команды. Прогресс цели оценивают в количественных показателях. К цели можно привязать проекты, портфели и задачи, чтобы видеть, какая работа ведется для ее достижения.
{% included (../_includes/entity-links.md) %}
Тип связи. Для проектов и портфелей:
* `depends on` — текущая сущность зависит от связанной
* `is dependent by` — текущая сущность блокирует связанную
* `works towards` — связь проекта с целью
Для цели:
* `parent entity` — родительская цель
* `child entity` — подцель
* `depends on` — текущая цель зависит от связанной
* `is dependent by` — текущая цель блокирует связанную
* `is supported by` — связь с проектом
{% endincluded %}