Создать виджет «Время цикла»

Запрос позволяет добавить виджет с диаграммой «Время цикла» на уже существующий дашборд.

POST

https://api.tracker.yandex.net/v3/dashboards/<id_дашборда>/widgets/cycleTime

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

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

Чтобы создать виджет, используйте HTTP-запрос с методом POST. В теле запроса укажите параметры в формате JSON.

POST /v3/dashboards/<id_дашборда>/widgets/cycleTime
Host: api.tracker.yandex.net
Authorization: OAuth <OAuth-токен>
X-Org-ID или X-Cloud-Org-ID: <идентификатор_организации>

{
    "description": "<название_виджета>",
    "query" | "filter" | "filterId" : "<фильтр задач>",
    "fromStatuses": [
        {
            "key": "<начальный_статус>"
        }
    ],
    "toStatuses": [
        {
            "key": "<конечный_статус>"
        }
    ],
    "excludedStatuses": [<исключаемые_статусы>],
    "includedStatuses": [<включаемые_статусы>],
    "bucket": {
        "unit": "<период_группировки>",
        "count": <количество_периодов>
    },
    "calendar": <идентификатор_календаря>,
    "lines": {
        "movingAverage": <true> | <false>,
        "standardDeviation": <true> | <false>,
        "percentile": [75, 83, 90],
        "cakePercentile": 85
    },
    "start": "now()-2w",
    "end": "now()-2d",
    "mode": "<режим_отображения_данных>",
    "autoUpdatable": <true> | <false>
}
Заголовки

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

  • Authorization: токен для авторизации в одном из форматов:

    • OAuth <OAuth-токен> при авторизации по протоколу OAuth 2.0. Читать подробнее

    • Bearer <IAM-токен> при авторизации с помощью IAM-токена — если к Tracker привязана организация Yandex Cloud Organization. Читать подробнее

  • X-Org-ID или X-Cloud-Org-ID: идентификатор организации.

    • Используйте заголовок X-Org-ID, если к Tracker привязана организация Яндекс 360 для бизнеса.

    • Используйте заголовок X-Cloud-Org-ID, если к Tracker привязана организация Yandex Cloud Organization.

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

Параметры тела запроса

Тело запроса содержит параметры виджета с диаграммой «Время цикла».

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

Параметр Описание Тип данных
description Название виджета. Строка

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

Параметр Описание Тип данных
query Фильтр задач на языке запросов. Строка
filter Фильтр задач в формате {"<поле>": "<значение>"}. Строка
filterId Идентификатор сохраненного фильтра. Строка
fromStatuses Ключ статуса, с которого началась работа над задачей. Время в указанном статусе не учитывается. По умолчанию расчет начинается с первого статуса в истории задачи. Массив
toStatuses Ключ статуса, на котором работа над задачей завершилась. Если задано несколько статусов, то будет использован самый поздний, в который переходила задача. По умолчанию расчет выполняется до последнего статуса в истории задачи. Массив
excludedStatuses Статусы, время нахождения в которых необходимо убрать из расчетов. Массив
includedStatuses статусы, время нахождения в которых необходимо добавить в расчеты. Массив
bucket Величина шага. Значение по умолчанию — 7 дней. Объект
calendar Идентификатор календаря для учета только рабочего времени. Если не задан, используется обычный календарь. Число
lines Настройки отображения оси времени. Объект
start Формула для начала расчета. Например, расчет за две последние недели: now() - 2w. Значение по умолчанию — 2 года. Строка
end Формула для окончания расчета. Например, для окончания расчета за два дня до текущей даты: now() - 2d. Значение по умолчанию — now(). Строка
mode Режим отображения данных:
  • common-lines — показывать выбранные графики (перцентиль, стандартное отклонение, скользящее среднее);
  • common-lines-and-points — показывать для выбранных графиков точки, соответствующие задачам;
  • status-lines — показывать выбранные графики для каждого из статусов.
 Строка
autoUpdatable Признак автоматического обновления диаграммы. Логический

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

Параметр Описание Тип данных
unit Период группировки дат:
  • days — дни;
  • weeks — недели;
  • months — месяцы;
  • sprints — спринты.
 Строка
count Количество периодов с выбранной группировкой. Если в поле unit выбрано sprints, то количество периодов всегда равно 1. Число
boardId Идентификатор доски задач. Доступно, если в поле unit выбрано sprints. Строка

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

Параметр Описание Тип данных
movingAverage Скользящее среднее. Опция, которая добавляет на график линию усредненного значения времени. С ее помощью можно увидеть, как задача проходит цикл по медиане. Логический
standardDeviation Стандартное отклонение. Опция, которая добавляет на график полосу среднеквадратичного отклонения. С ее помощью вы можете оценить, насколько широко значения рассеяны от среднего значения. Логический
percentile Процент значений в выборке данных, относительно которого вычисляется перцентиль. Массив
cakePercentile Значение перцентиля для построения диаграммы, в которой каждый статус отображается отдельно. Число

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

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

Тело ответа содержит JSON-объект с параметрами нового виджета.

{
    "id": 123456,
    "version": 1,
    "createdBy": {
        "self": "https://api.tracker.yandex.net/v3/users/12********",
        "id": "44********",
        "display": "Иван Иванов",
        "passportUid": 12********
    },
    "description": "Диаграмма «Время цикла»",
    "color": 0,
    "dashboard": {
        "self": "https://api.tracker.yandex.net/v3/dashboards/118899",
        "id": "118899",
        "display": "Дашборд"
    },
    "fromStatuses": [
        {
            "self": "https://api.tracker.yandex.net/v3/statuses/1",
            "id": "1",
            "key": "open",
            "display": "Открыт"
        }
    ],
    "toStatuses": [
        {
            "self": "https://api.tracker.yandex.net/v3/statuses/3",
            "id": "3",
            "key": "closed",
            "display": "Закрыт"
        }
    ],
    "bucket": {
        "type": "days",
        "count": 2
    },
    "calendar": {
        "id": "1",
        "display": "Москва. Будни, 11:00−20:00"
    },
    "query": "Queue: TEST Assignee: me()",
    "datasetInfo": {
        "status": "created",
        "buildStartedAt": "2024-04-15T20:58:07.957+0000",
        "builtBy": {
            "self": "https://api.tracker.yandex.net/v3/users/12********",
            "id": "44********",
            "display": "Иван Иванов",
            "passportUid": 12********
        }
    },
    "lines": {
        "standardDeviation": true,
        "movingAverage": true,
        "percentile": [
            83.0,
            90.0,
            75.0
        ],
        "cakePercentile": 85.0
    },
    "start": "now()-2w",
    "end": "now()-2d",
    "mode": "common-lines-and-points",
    "self": "https://api.tracker.yandex.net/v3/widgets/123456"
}
Параметры ответа
Параметр Описание Тип данных
id Идентификатор виджета. Число
version Версия виджета. Каждое изменение виджета увеличивает номер версии. Число
createdBy Объект с информацией о создателе виджета. Объект
description Название виджета. Строка
color Служебный параметр. Число
dashboard Объект с информацией о дашборде, на котором размещен виджет. Объект
fromStatuses Объект с информацией о статусе, с которого началась работа над задачей. Объект
toStatuses Объект с информацией о статусе, на котором работа над задачей завершилась. Объект
bucket Объект с информацией о величине шага. Объект
calendar Объект с информацией о графике рабочего времени. Объект
query | filter | filterId Фильтр задач в выбранном формате. Строка
datasetInfo Объект с информацией о расчете. Объект
lines Объект с информацией об оси времени. Объект
start Формула для начала расчета. Строка
end Формула для окончания расчета. Строка
mode Режим отображения данных. Строка
self Адрес ресурса API, который содержит параметры виджета. Строка

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

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

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

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

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

Параметр Описание Тип данных
type Период группировки дат:
  • days — дни;
  • weeks — недели;
  • months — месяцы;
  • sprints — спринты.
 Строка
count Количество периодов с выбранной группировкой. Если в поле unit выбрано sprints, то количество периодов всегда равно 1. Число
boardId Идентификатор доски задач. Доступно, если в поле unit выбрано sprints. Строка

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

Параметр Описание Тип данных
id Идентификатор графика рабочего времени. Строка
display Название графика рабочего времени. Строка

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

Параметр Описание Тип данных
status Статус расчета. Строка
buildStartedAt Дата и время запуска расчета в формате: YYYY-MM-DDThh:mm:ss.sss±hhmm. Строка
builtBy Объект с информацией о пользователе, создавшем виджет. Объект

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

Параметр Описание Тип данных
standardDeviation Признак отображения графика стандартного отклонения. Логический
movingAverage Признак отображения графика скользящего среднего. Логический
percentile Список значений в выборке данных в процентах, относительно которых вычисляется перцентиль. Массив
cakePercentile Значение перцентиля для построения диаграммы, в которой каждый статус отображается отдельно. Число

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

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