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

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

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

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

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

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

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

POST /v2/dashboards/<идентификатор_дашборда>/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:

    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 для бизнеса.
Параметры тела запроса

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

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

Параметр Описание Тип данных
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/v2/users/12********",
        "id": "44********",
        "display": "Иван Иванов",
        "passportUid": 12********
    },
    "description": "Диаграмма «Время цикла»",
    "color": 0,
    "dashboard": {
        "self": "https://api.tracker.yandex.net/v2/dashboards/118899",
        "id": "118899",
        "display": "Дашборд"
    },
    "fromStatuses": [
        {
            "self": "https://api.tracker.yandex.net/v2/statuses/1",
            "id": "1",
            "key": "open",
            "display": "Открыт"
        }
    ],
    "toStatuses": [
        {
            "self": "https://api.tracker.yandex.net/v2/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/v2/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/v2/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. Число

Поля объекта 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 временно недоступен.
Предыдущая
Создать дашборд
Следующая
Получить список компонентов