Связаться с намиПодключиться

Создать сущность

Статья создана
Обновлена 26 августа 2024 г.

Запрос позволяет создать новую сущность — проект или портфель проектов.

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

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

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

Чтобы создать новую сущность, используйте HTTP-запрос с методом POST. Параметры запроса передаются в его теле в формате JSON.

POST /v2/entities/{entityType}
Host: api.tracker.yandex.net
Authorization: OAuth <OAuth-токен>
X-Org-ID или X-Cloud-Org-ID: <идентификатор_организации>

{
   "fields": 
   {
      "summary": "<название>",
      "teamAccess": true
   }
}
Заголовки

  • Host

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

    api.tracker.yandex.net

  • Authorization

    OAuth-токен в формате OAuth <OAuth-токен>, например:

    OAuth 0c4181a7c2cf4521964a72ff********

  • X-Org-ID или X-Cloud-Org-ID

    Идентификатор организации. Узнать его можно на странице организаций Tracker.

    • Если к Tracker привязана только организация Яндекс 360 для бизнеса, используется заголовок X-Org-ID.
    • Если к Tracker привязана только организация Yandex Cloud Organization, используется заголовок X-Cloud-Org-ID.
    • Если к Tracker одновременно привязаны организации Яндекс 360 для бизнеса и Yandex Cloud Organization, используется заголовок X-Org-ID и идентификатор организации Яндекс 360 для бизнеса.
Ресурс

Ресурс

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

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

Параметр Описание Тип данных
fields Дополнительные поля сущности, которые будут включены в ответ. Строка
Параметры тела запроса

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

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

Параметр Описание Тип данных
fields Объект с настройками сущности. Объект

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

Параметр Описание Тип данных
summary Название (обязательное поле). Строка
teamAccess Доступ. Логический
description Описание. Строка
author Автор (идентификатор пользователя). Число
lead Ответственный (идентификатор пользователя). Число
teamUsers Участники (массив идентификаторов пользователей). Массив чисел
clients Заказчики (массив идентификаторов пользователей). Массив чисел
followers Наблюдатели (массив идентификаторов пользователей). Массив чисел
start Дата начала в формате YYYY-MM-DDThh:mm:ss.sss±hhmm. Дата
end Дедлайн в формате YYYY-MM-DDThh:mm:ss.sss±hhmm. Дата
tags Теги. Массив строк
parentEntity Идентификатор родительской сущности (поле «Входит в портфель»). Передается только значение для поля «Основной портфель». Число
entityStatus Статус:
  • draft — Черновик;
  • in_progress — В работе;
  • launched — Новый;
  • postponed — Отложен;
  • at_risk — Есть риски;
  • blocked — Заблокирован;
  • according_to_plan — По плану.
 Строка

Пример: Создать проект

  • Используется HTTP-метод POST.
  • Создается проект с названием «Test Project».
POST /v2/entities/project/ HTTP/1.1
Host: api.tracker.yandex.net
Authorization: OAuth <OAuth-токен>
X-Org-ID или X-Cloud-Org-ID: <идентификатор_организации>

{
    "fields":
    {
       "summary":"Test Project"
    }
}

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

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

Тело ответа содержит информацию о созданной сущности в формате JSON.

{
   "self": "https://api.tracker.yandex.net/v2/entities/project/655f3be523db2132********",
   "id": "655f3be523db2132********",
   "version": 1,
   "shortId": 6,
   "entityType": "project",
   "createdBy": { "self": "https://api.tracker.yandex.net/v2/users/11********", "id": "11********", "display": "Имя Фамилия", "cloudUid": "ajevuhegoggfk*******", "passportUid": 11******** },
   "createdAt": "2023-11-23T11:47:49.743+0000",
   "updatedAt": "2023-11-23T11:47:49.743+0000"
}
Параметры ответа
Параметр Описание Тип данных
self Адрес ресурса API, который содержит информацию о сущности. Строка
id Идентификатор сущности. Строка
version Версия сущности. Каждое изменение параметров увеличивает номер версии. Число
shortId Идентификатор проекта или портфеля. Строка
entityType Тип сущности. Строка
createdBy Блок с информацией о создателе сущности. Объект
createdAt Дата создания сущности в формате YYYY-MM-DDThh:mm:ss.sss±hhmm. Строка
updatedAt Дата последнего обновления сущности в формате YYYY-MM-DDThh:mm:ss.sss±hhmm. Строка

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

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

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

400
Один или несколько параметров запроса имеют недопустимое значение.
401
Пользователь не авторизован. Проверьте, были ли выполнены действия, описанные в разделе Доступ к API.
403
У вас не хватает прав на выполнение этого действия. Наличие прав можно перепроверить в интерфейсе Tracker — для выполнения действия при помощи API и через интерфейс требуются одинаковые права.
404
Запрошенный объект не был найден. Возможно, вы указали неверное значение идентификатора или ключа объекта.
409
При редактировании объекта возник конфликт. Возможно, ошибка возникла из-за неправильно указанной версии изменений.
Предыдущая
Проекты и портфели. Обзор
Следующая
Получить параметры сущности