Проекты, портфели и цели

API Entities (Сущности) представляет унифицированный набор методов для управления целями, проектами или портфелями, более гибкий и функциональный.

С помощью данного API вы сможете:

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

Тело запросов для управления сущностями и ответов на запросы может содержать объект fields с дополнительными параметрами сущности. Список допустимых полей объекта fields приведен в таблице ниже.

Для редактирования параметров сущности можно использовать операторы set, add, remove и другие. Подробнее читайте в разделе Редактирование параметров.

Чтобы включить дополнительные параметры в тело ответа, добавьте в адрес запроса параметр fields и укажите одно или несколько значений.

Пример: Включить в ответ описание проекта и информацию о пунктах чеклиста.

POST https://api.tracker.yandex.net/v3/entities/project/12345/checklistItems?fields=description,checklistItems

В тело ответа будет включен объект fields с запрашиваемой информацией.

Поле

Описание

Тип данных

Тип сущности

summary

Название сущности

Строка

Проект
Портфель
Цель

description

Описание сущности

Строка

Проект
Портфель
Цель

author

Автор

Объект

Проект
Портфель
Цель

lead

Ответственный

Объект

Проект
Портфель
Цель

teamUsers

Участники

Массив объектов

Проект
Портфель
Цель

clients

Заказчики

Массив объектов

Проект
Портфель
Цель

followers

Наблюдатели

Массив объектов

Проект
Портфель
Цель

start

Дата начала в формате YYYY-MM-DD

Строка

Проект
Портфель

end

Дедлайн в формате YYYY-MM-DD

Строка

Проект
Портфель
Цель

quarter

Квартал начала работы и квартал дедлайна в формате YYYY QN

Массив строк

Проект
Портфель

metricItems

Метрики — виджеты с дашбордов. Подробнее о метриках

Массив объектов

Проект
Портфель
Цель

checklistItems

Чеклист в проектах и портфелях. Подробнее о чеклистах

Массив объектов

Проект
Портфель

keyResultItems

Список ключевых результатов в целях. Подробнее о ключевых результатах

Массив объектов

Цель

progressPercentage

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

Может иметь значение от 0 до 1. Если подцелей и ключевых результатов нет, значение равно null.

Параметр доступен только для чтения

Число

Цель

tags

Теги

Массив строк

Проект
Портфель
Цель

parentEntity

Данные о родительских сущностях. Для проекта и портфеля — поле «Входит в портфель»

Объект

Проект
Портфель
Цель

teamAccess

Настройки доступа:

  • true— доступ только для участников проекта, портфеля или цели
  • false — доступ имеют другие пользователи, кроме участников проекта, портфеля или цели

Эта опция не действует, если настройки доступа унаследованы от родительской сущности — см. описание параметра permissionSources

Строка

Проект
Портфель
Цель

entityStatus

Статус

Для проекта или портфеля:

  • draft — Новый;
  • draft2 — Черновик;
  • in_progress — В работе;
  • according_to_plan — По плану;
  • postponed — Отложен;
  • at_risk — Есть риски;
  • blocked — Заблокирован;
  • launched — Завершен;
  • cancelled — Отменен.

Для цели:

  • draft — Новая;
  • according_to_plan — По плану;
  • at_risk — Есть риски;
  • blocked — Заблокирована;
  • achieved — Достигнута;
  • partially_achieved — Частично достигнута;
  • not_achieved — Не достигнута;
  • exceeded — Превышена;
  • cancelled — Отменена.

Строка

Проект
Портфель
Цель

issueQueues

Очереди, задачи которых входят в проект. Параметр доступен только для чтения

Массив объектов

Проект

lastCommentUpdatedAt

Дата последнего комментария в формате YYYY-MM-DD

Строка

Проект
Портфель
Цель

linkedGoalsCount

Количество связанных целей

Число

Проект
Портфель

linkedProjectsCount

Количество связанных проектов и портфелей

Число

Цель

Поля объектов, содержащих данные пользователей

Параметры сущности author, lead, teamUsers, clients, followers содержат объекты со следующими полями:

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

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

Параметр Описание Тип данных
id Идентификатор метрики Строка
text Название метрики Строка
url Ссылка на виджет Строка

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

Параметр Описание Тип данных
id Идентификатор пункта чеклиста. Строка
text Текст пункта чеклиста. Строка
textHtml Текст пункта чеклиста в формате HTML. Строка
checked Признак выполнения пункта чеклиста:
  • true — пункт отмечен как выполненный;
  • false — пункт не отмечен как выполненный.
 Логический
assignee Исполнитель пункта чеклиста. Объект
deadline Крайний срок исполнения пункта чеклиста. Объект
checklistItemType Тип пункта чеклиста. Строка

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

Параметр Описание Тип данных
id Идентификатор пункта чеклиста Строка
text Текст ключевого результата Строка
type Способ измерения прогресса ключевого результата:
  • value — по значению;
  • binary — по факту.
 Строка
deadline Срок достижения ключевого результата Объект
progress Количественные показатели при способе измерения прогресса «по значению» Объект
achieved Признак достижения ключевого результата:
  • true — отмечен как достигнутый;
  • false — не отмечен как достигнутый.
 Логический
assignee Исполнитель ключевого результата Объект

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

Параметр Описание Тип данных
date Предельный срок в формате YYYY-MM-DDThh:mm:ss.sss±hhmm. Дата
deadlineType Тип дедлайна:
  • date — дата;
  • quarter — квартал.
 Строка
isExceeded Признак наступления дедлайна:
  • true — предельный срок наступил;
  • false — предельный срок не наступил.
 Логический

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

Параметр Описание Тип данных
start Значение прогресса ключевого результата в начале работы Число
end Значение прогресса ключевого результата, которого нужно достичь Число
current Значение прогресса ключевого результата в данный момент Число

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

Параметр Описание Тип данных
primary Основной портфель (для проектов и портфелей) или родительская цель (для целей) Объект
secondary Для проектов и портфелей — список дополнительных портфелей
Для целей значение параметра всегда пусто		 Массив объектов

Если в адресе запроса указана версия API v2, объект parentEntity содержит информацию только об основном портфеле или родительской цели.

Поля объекта, содержащего данные сущности

Параметры primary и secondary содержат объекты со следующими полями:

Параметр Описание Тип данных
self Адрес ресурса API, который содержит информацию о сущности Строка
id Идентификатор сущности Строка
display Название сущности Строка

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

Параметр Описание Тип данных
self Адрес ресурса API, который содержит информацию об очереди. Строка
id Идентификатор очереди. Строка
key Ключ очереди. Строка
display Отображаемое название очереди. Строка
Предыдущая
Редактировать локальное поле очереди
Следующая
Создать сущность