Импортировать виджет

Запрос позволяет импортировать виджет на уже существующий дашборд. При импорте можно указать автора createdBy и дату создания start.

Чтобы разместить виджет на дашборде, добавьте его через параметр widgets.add запроса Обновить дашборд. До этого виджет не виден на дашборде и не возвращается в поле widgets запроса Получить дашборд.

POST

https://api.tracker.yandex.net/v3/dashboards/{id_дашборда}/widgets/_import

Запрос может быть выполнен только от имени администратора.

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

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

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

POST /v3/dashboards/{id_дашборда}/widgets/_import
Host: api.tracker.yandex.net
Authorization: OAuth API_TOKEN
Content-Type: application/json
X-Org-ID или X-Cloud-Org-ID: ИДЕНТИФИКАТОР_ОРГАНИЗАЦИИ

{
    "type": "filter",
    "description": "НАЗВАНИЕ_ВИДЖЕТА",
    "perPage": 10,
    "fields": ["summary"],
    "filterParams": {
        "filter": {
            "author": "me()"
        }
    },
    "createdBy": "ЛОГИН_ПОЛЬЗОВАТЕЛЯ",
    "start": "2025-02-18T16:35:41.740+0000"
}

Заголовки

Host: адрес узла, предоставляющего API.
Authorization: токен для авторизации в одном из форматов:
- OAuth OAUTH_TOKEN при авторизации по протоколу OAuth 2.0. Читать подробнее
- Bearer IAM_TOKEN при авторизации с помощью IAM-токена — если к Трекеру привязана организация Yandex Identity Hub. Читать подробнее
Content-Type: формат тела запроса. Должен иметь значение application/json.
X-Org-ID или X-Cloud-Org-ID: идентификатор организации.
- если к Трекеру привязана организация Яндекс 360 для бизнеса, используйте заголовок X-Org-ID,
- если к Трекеру привязана организация Yandex Identity Hub, используйте заголовок X-Cloud-Org-ID.
Чтобы узнать идентификатор организации, перейдите на страницу Администрирование → Организации и скопируйте значение поля идентификатор.

Ресурс

Параметр	Описание	Тип данных
id_дашборда	Идентификатор дашборда.	Число

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

Укажите type и параметры выбранного типа виджета.

Параметр	Описание	Тип данных
type	Тип виджета. Допустимые значения: `info` — виджет «Полезные ссылки»; `security` — виджет безопасности; `filter` — виджет «Задачи»; `created-vs-resolved` — график «Создано/Решено»; `issues` — виджет «Статистика по задачам»; `table-sum` — виджет «Сводная таблица с суммой»; `table` — виджет «Сводная таблица»; `time-since` — виджет «График событий»;	Строка
description	Название виджета. Обязателен при создании и импорте.	Строка
color	Цвет виджета. Необязательный параметр.	Число
refresh	Период обновления виджета. Необязательный параметр.	Число
createdBy	Логин автора виджета. Обязательный параметр.	Строка
start	Дата и время создания виджета в формате `YYYY-MM-DDThh:mm:ss.sss±hhmm`. Обязательный параметр.	Строка

Параметры типов виджетов

Укажите поля из строки выбранного типа. Для создания и импорта параметры из второго столбца обязательны.

Тип виджета	Обязательные параметры	Необязательные параметры
`info`	`subtype`: `links`, `presets`, `test_drive`	—
`security`	`fields`, `perPage`	`queues`
`filter`	`fields`, `perPage`, `filterParams`	—
`created-vs-resolved`	`filterParams`	`groupBy`, `daysCount`, `cumulative`, `unresolvedIssuesTrend`, `versions`: `all`, `main`, `none`
`issues`	`filterParams`, `field`, `perPage`	`orderBySum`, `orderAsc`
`table`	`filterParams`, `fieldX`, `fieldY`, `perPage`	`showSum`, `orderBySum`, `orderAsc`
`table-sum`	`filterParams`, `rowField`, `columnField`, `sumField`, `initialRowsLimit`	`showTotals`, `rowOrderAsc`, `columnOrderAsc`
`time-since`	`filterParams`, `field`	`groupBy`, `daysCount`, `cumulative`

Параметр	Описание
subtype	Подтип полезных ссылок: `links`, `presets` или `test_drive`.
fields	Отображаемые поля. Для виджетов задач см. описание массива.
perPage	Число элементов на странице виджета.
queues	Очереди виджета безопасности.
filterParams	Параметры фильтрации задач. См. описание объекта.
field	Поле группировки.
fieldX, fieldY	Поля осей таблицы. `fieldY` должно отличаться от `fieldX`.
rowField, columnField	Поля строк и столбцов. `columnField` должно отличаться от `rowField`.
sumField	Поле для расчета суммы.
initialRowsLimit	Начальное число строк: от 1 до 200.
showSum, showTotals	Отображение суммы и итогов.
orderBySum, orderAsc	Сортировка по сумме и по возрастанию.
rowOrderAsc, columnOrderAsc	Сортировка строк и столбцов по возрастанию.
groupBy	Группировка: `hour`, `day`, `week`, `month`, `quarter`, `year`.
daysCount	Период группировки. По умолчанию — 30. Максимум зависит от `groupBy`: `hour` — 10, `day` — 300, `week` — 1750, остальные — 3500.
cumulative	Накопительный режим графика.
unresolvedIssuesTrend	Отображение динамики нерешенных задач.
versions	Версии для графика «Создано/Решено»: `all`, `main`, `none`.

Элементы массива fields

Параметр fields определяет, какие поля задач будут отображаться в виджете. Каждый элемент массива — ключ поля задачи. Например, ["summary"] — в виджете будет отображаться только колонка с названием задачи.

Примеры ключей стандартных полей задач:

Параметр	Описание
key	Ключ задачи.
summary	Название задачи.
status	Статус задачи.
assignee	Исполнитель задачи.
priority	Приоритет задачи.
created	Дата создания задачи.
updated	Дата обновления задачи.

Полный список полей задачи доступен в интерфейсе Трекера на странице Администрирование → Поля (https://tracker.yandex.ru/admin/fields). Список полей также можно получить через API — запрос GET /v3/fields.

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

Параметр	Описание	Тип данных
filter	Фильтр задач по параметрам в формате `{"ПОЛЕ": "ЗНАЧЕНИЕ"}`.	Объект
query	Фильтр задач на языке запросов.	Строка

Если в теле запроса одновременно указаны параметры filter и query, приоритетным источником задач будет query (язык запросов).

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

Запрос выполнен успешно

Запрос выполнен с ошибкой

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

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

Набор полей зависит от типа виджета. Ниже приведен пример ответа для filter. Поля раскладки возвращает только запрос Получить виджет.

{
    "id": 123456,
    "version": 1,
    "type": "filter",
    "self": "https://api.tracker.yandex.net/v3/widgets/123456",
    "dashboard": {
        "self": "https://api.tracker.yandex.net/v3/dashboards/18",
        "id": "18",
        "display": "Новый дашборд"
    },
    "createdBy": {
        "self": "https://api.tracker.yandex.net/v3/users/11********",
        "id": "11********",
        "display": "Имя Фамилия",
        "cloudUid": "ajeppa7dgp53********",
        "passportUid": 1100000000000000
    },
    "description": "new desc",
    "color": 0,
    "createdAt": "2026-08-27T10:34:30.363+0000",
    "fields": [
        {
            "self": "https://api.tracker.yandex.net/v3/fields/summary",
            "id": "summary",
            "name": "Задача",
            "key": "summary",
            "version": 0,
            "schema": {
                "type": "string",
                "required": true
            },
            "readonly": false,
            "options": false,
            "suggest": false,
            "queryProvider": {
                "type": "SummaryQueryProvider"
            },
            "order": 6,
            "category": {
                "self": "https://api.tracker.yandex.net/v3/fields/categories/000000000000000000000001",
                "id": "000000000000000000000001",
                "display": "Системные"
            },
            "type": "standard"
        }
    ],
    "perPage": 10,
    "filterParams": {
        "filter": {
            "author": "Автор"
        }
    }
}

Параметры ответа

Параметр	Описание	Тип данных
id	Идентификатор виджета.	Число
version	Версия виджета.	Число
type	Тип виджета.	Строка
self	Адрес ресурса API, который содержит параметры виджета.	Строка
dashboard	Объект с информацией о дашборде, на котором размещен виджет.	Объект
createdBy	Объект с информацией о создателе виджета.	Объект
description	Название виджета.	Строка
color	Служебный параметр.	Число
createdAt	Дата и время создания виджета в формате `YYYY-MM-DDThh:mm:ss.sss±hhmm`.	Строка
fields	Массив объектов с информацией о полях задач, отображаемых в виджете.	Массив объектов
perPage	Количество задач на одной странице виджета.	Число
filterParams	Параметры фильтрации задач для виджета.	Объект

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

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

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

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

Поля элементов массива fields

Параметр	Описание	Тип данных
self	Адрес ресурса API, который содержит параметры поля.	Строка
id	Идентификатор поля.	Строка
name	Название поля.	Строка
key	Ключ поля.	Строка
version	Версия поля.	Число
schema	Схема поля.	Объект
readonly	Признак того, что поле доступно только для чтения.	Логический
options	Признак того, что поле имеет фиксированный набор значений.	Логический
suggest	Признак того, что для поля доступны подсказки.	Логический
queryProvider	Провайдер запросов для поля.	Объект
order	Порядок отображения поля.	Число
category	Категория поля.	Объект
type	Тип поля.	Строка

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

Параметр	Описание	Тип данных
type	Тип данных поля.	Строка
required	Признак того, что поле обязательно для заполнения.	Логический

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

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

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

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

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

Параметр	Описание	Тип данных
filter	Фильтр задач по параметрам.	Объект
query	Фильтр задач на языке запросов, если он задан.	Строка

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

400: Один или несколько параметров запроса имеют недопустимое значение.

403: У вас не хватает прав на выполнение этого действия. Наличие прав можно перепроверить в интерфейсе Трекера — для выполнения действия при помощи API и через интерфейс требуются одинаковые права.

404: Запрошенный объект не был найден. Возможно, вы указали неверное значение идентификатора или ключа объекта.

422: Ошибка валидации JSON, запрос отклонен.

500: Внутренняя ошибка сервиса. Попробуйте повторно отправить запрос через некоторое время.

503: Сервис API временно недоступен.

Была ли статья полезна?

Обновить виджет

Получить список компонентов