[comment]: # ({bc57ee5e-e5d5266e})
# 29 Элементы данных верхнего уровня
[comment]: # ({/bc57ee5e-e5d5266e})
[comment]: # ({b96fa072-b8507936})
### Описание
Эти параметры и возможные значения свойств для соответствующих объектов полей виджета позволяют настраивать виджет [*Top items*](/manual/web_interface/frontend_sections/dashboards/widgets/top_items) в методах `dashboard.create` и `dashboard.update`.
::: noteimportant
Свойства `fields` виджета не проверяются при создании или обновлении панели мониторинга.
Это позволяет пользователям изменять [встроенные виджеты](/manual/web_interface/frontend_sections/dashboards/widgets) и создавать [пользовательские виджеты](/devel/modules/tutorials/widget), но также создает риск некорректного создания или обновления виджетов.
Чтобы обеспечить успешное создание или обновление виджета *Top items*, ознакомьтесь с поведением параметров, описанным в таблицах ниже.
:::
[comment]: # ({/b96fa072-b8507936})
[comment]: # ({612eaf3d-2a023c70})
### Параметры
Для виджета *Top items* поддерживаются следующие параметры.
|Параметр|<|[type](/manual/api/reference/dashboard/object#dashboard-widget-field)|name|value|
|-|--------|--|--------|-------------------------------|
|*Интервал обновления*|<|0|rf_rate|0 - Не обновлять;
10 - 10 секунд;
30 - 30 секунд;
60 - *(по умолчанию)* 1 минута;
120 - 2 минуты;
600 - 10 минут;
900 - 15 минут.|
|*Группы узлов сети*|<|2|groupids.0|ID [группы узлов сети](/manual/api/reference/hostgroup/get).
Примечание: Чтобы настроить несколько групп узлов сети, создайте объект поля виджета панели с увеличивающимся номером в имени свойства для каждой группы узлов сети.
Этот параметр не поддерживается при настройке виджета на [панели шаблона](/manual/api/reference/templatedashboard/object).|
|<|*Группы узлов сети (Виджет)*|1|groupids.\_reference|Вместо ID [группы узлов сети](/manual/api/reference/hostgroup/get):
`ABCDE._hostgroupids` — укажите [совместимый виджет](/manual/web_interface/frontend_sections/dashboards/widgets#widget-compatibility) (с параметром *Reference*, установленным в "`ABCDE`") в качестве источника данных для групп узлов сети.
Этот параметр не поддерживается при настройке виджета на [панели шаблона](/manual/api/reference/templatedashboard/object).|
|*Узлы сети*|<|3|hostids.0|ID [узла сети](/manual/api/reference/host/get).
Примечание: Чтобы настроить несколько узлов сети, создайте объект поля виджета панели с увеличивающимся номером в имени свойства для каждого узла сети. Для нескольких узлов сети параметр *Группы узлов сети* либо не должен быть настроен вовсе, либо должен быть настроен как минимум с одной группой узлов сети, которой принадлежат указанные узлы сети.
Этот параметр не поддерживается при настройке виджета на [панели шаблона](/manual/api/reference/templatedashboard/object).|
|<|*Узлы сети (Виджет/Панель)*|1|hostids.\_reference|Вместо ID [узла сети](/manual/api/reference/host/get):
`DASHBOARD.hostids` — укажите [селектор узлов сети](/manual/web_interface/frontend_sections/dashboards/widgets#override-host) панели в качестве источника данных для узлов сети;
`ABCDE._hostids` — укажите [совместимый виджет](/manual/web_interface/frontend_sections/dashboards/widgets#widget-compatibility) (с параметром *Reference*, установленным в "`ABCDE`") в качестве источника данных для узлов сети.
Этот параметр не поддерживается при настройке виджета на [панели шаблона](/manual/api/reference/templatedashboard/object).|
|*Теги узлов сети*|<|<|<|<|
|<|*Тип вычисления*|0|host_tags_evaltype|0 - *(по умолчанию)* И/Или;
2 - Или.
Этот параметр не поддерживается при настройке виджета на [панели шаблона](/manual/api/reference/templatedashboard/object).|
|^|*Имя тега*|1|host_tags.0.tag|Любое строковое значение.
Примечание: Номер в имени свойства указывает на порядок тега в списке вычисления тегов.
[Поведение параметра](/manual/api/reference_commentary#parameter-behavior):
- *обязательно* при настройке *Тегов узлов сети*
Этот параметр не поддерживается при настройке виджета на [панели шаблона](/manual/api/reference/templatedashboard/object).|
|^|*Оператор*|0|host_tags.0.operator|0 - Содержит;
1 - Равно;
2 - Не содержит;
3 - Не равно;
4 - Существует;
5 - Не существует.
Примечание: Номер в имени свойства указывает на порядок тега в списке вычисления тегов.
[Поведение параметра](/manual/api/reference_commentary#parameter-behavior):
- *обязательно* при настройке *Тегов узлов сети*
Этот параметр не поддерживается при настройке виджета на [панели шаблона](/manual/api/reference/templatedashboard/object).|
|^|*Значение тега*|1|host_tags.0.value|Любое строковое значение.
Примечание: Номер в имени свойства указывает на порядок тега в списке вычисления тегов.
[Поведение параметра](/manual/api/reference_commentary#parameter-behavior):
- *обязательно* при настройке *Тегов узлов сети*
Этот параметр не поддерживается при настройке виджета на [панели шаблона](/manual/api/reference/templatedashboard/object).|
|*Макет*|<|0|layout|0 - *(по умолчанию)* Горизонтальный;
1 - Вертикальный.|
|*Показывать проблемы*|<|0|show_problems|0 - Все;
1 - *(по умолчанию)* Неподавленные;
2 - Нет.|
|*Элементы данных* (см. ниже)|<|<|<|<|
[comment]: # ({/612eaf3d-2a023c70})
[comment]: # ({2cd9fffe-advanced})
#### Расширенная настройка
Для виджета *Top items* поддерживаются следующие параметры расширенной настройки.
|Параметр|<|[type](/manual/api/reference/dashboard/object#dashboard-widget-field)|name|value|
|-|--------|--|--------|-------------------------------|
|***Сортировка узлов сети***|<|<|<|<|
|*Сортировать по*|<|0|host_ordering_order_by|0 - *(по умолчанию)* Имя узла сети;
3 - Значение элемента данных.|
|<|*Шаблоны элементов данных*|1|host_ordering_item.0|Имя или шаблон [элемента данных](/manual/api/reference/item/get) (например, "\*: Number of processed \*values per second").
Примечание: Чтобы настроить несколько шаблонов элементов данных, создайте объект поля виджета панели мониторинга для каждого шаблона элемента данных с увеличивающимся номером в имени свойства.
При настройке виджета на [панели мониторинга шаблона](/manual/api/reference/templatedashboard/object) следует задавать только шаблоны для элементов данных, настроенных в шаблоне.
[Поведение параметра](/manual/api/reference_commentary#parameter-behavior):
- *обязательно*, если для *Сортировать по* установлено значение "Значение элемента данных"|
|*Порядок*|<|0|host_ordering_order|2 - *(по умолчанию)* Верхние N;
3 - Нижние N.|
|*Лимит*|<|0|host_ordering_limit|Допустимые значения: от 1 до 100.
По умолчанию: 10.|
|***Сортировка элементов данных***|<|<|<|<|
|*Сортировать по*|<|0|item_ordering_order_by|1 - Узел сети;
2 - Имя элемента данных;
3 - *(по умолчанию)* Значение элемента данных.|
|<|*Шаблоны узлов сети*|1|item_ordering_host.0|Имя или шаблон [узла сети](/manual/api/reference/host/get).
Примечание: Чтобы настроить несколько шаблонов узлов сети, создайте объект поля виджета панели мониторинга для каждого шаблона узла сети с увеличивающимся номером в имени свойства.
[Поведение параметра](/manual/api/reference_commentary#parameter-behavior):
- *обязательно*, если для *Сортировать по* установлено значение "Узел сети"|
|*Порядок*|<|0|item_ordering_order|2 - *(по умолчанию)* Верхние N;
3 - Нижние N.|
|*Лимит*|<|0|item_ordering_limit|Допустимые значения: от 1 до 100.
По умолчанию: 10.|
[comment]: # ({/2cd9fffe-advanced})
[comment]: # ({e913fe7b-f35f175e})
### Столбцы
::: noteclassic
Первое число в имени свойства (например, columns.0.items.0, columns.0.item_tags_evaltype) обозначает конкретный столбец, а второе число, если оно присутствует, обозначает настроенную сущность (например, шаблон элемента данных, тег).
:::
|Параметр|<|[type](/manual/api/reference/dashboard/object#dashboard-widget-field)|name|value|
|-|--------|--|--------|-------------------------------|
|*Шаблоны элементов данных*|<|1|columns.0.items.0|Имя или шаблон [элемента данных](/manual/api/reference/item/get) (например, "\*: Number of processed \*values per second").
Примечание: Чтобы настроить несколько шаблонов элементов данных, создайте объект поля виджета панели с отдельным шаблоном элемента данных для каждого из них, увеличивая второе число в имени свойства.
При настройке виджета на [панели шаблона](/manual/api/reference/templatedashboard/object) следует задавать только шаблоны для элементов данных, настроенных в шаблоне.
[Поведение параметра](/manual/api/reference_commentary#parameter-behavior):
- *обязателен*|
|*Теги элементов данных*|<|<|<|<|
|<|*Тип вычисления*|0|columns.0.item_tags_evaltype|0 - *(по умолчанию)* And/Or;
2 - Or.|
|^|*Имя тега*|1|columns.0.item_tags.0.tag|Любое строковое значение.
Примечание: Второе число в имени свойства указывает на порядок тега в списке вычисления тегов.
[Поведение параметра](/manual/api/reference_commentary#parameter-behavior):
- *обязателен* при настройке *Тегов элементов данных*|
|^|*Оператор*|0|columns.0.item_tags.0.operator|0 - Содержит;
1 - Равно;
2 - Не содержит;
3 - Не равно;
4 - Существует;
5 - Не существует.
Примечание: Второе число в имени свойства указывает на порядок тега в списке вычисления тегов.
[Поведение параметра](/manual/api/reference_commentary#parameter-behavior):
- *обязателен* при настройке *Тегов элементов данных*|
|^|*Значение тега*|1|columns.0.item_tags.0.value|Любое строковое значение.
Примечание: Второе число в имени свойства указывает на порядок тега в списке вычисления тегов.
[Поведение параметра](/manual/api/reference_commentary#parameter-behavior):
- *обязателен* при настройке *Тегов элементов данных*|
|*Базовый цвет*|<|1|columns.0.base_color|Шестнадцатеричный код цвета (например, `FF0000`).|
|*Отображать значение как*|<|0|columns.0.display_value_as|1 - *(по умолчанию)* Число;
2 - Текст.|
|*Отображение*|<|0|columns.0.display|1 - *(по умолчанию)* Как есть;
2 - Полоса;
3 - Индикаторы;
6 - Спарклайн.|
|*Мин*|<|1|columns.0.min|Любое числовое значение. Поддерживаются [суффиксы](/manual/appendix/suffixes) (например, "1d", "2w", "4K", "8G").
[Поведение параметра](/manual/api/reference_commentary#parameter-behavior):
- *поддерживается*, если *Отображать значение как* установлено в "Число", а *Отображение* установлено в "Полоса" или "Индикаторы"|
|*Макс*|<|1|columns.0.max|Любое числовое значение. Поддерживаются [суффиксы](/manual/appendix/suffixes) (например, "1d", "2w", "4K", "8G").
[Поведение параметра](/manual/api/reference_commentary#parameter-behavior):
- *поддерживается*, если *Отображать значение как* установлено в "Число", а *Отображение* установлено в "Полоса" или "Индикаторы"|
|*Спарклайн*|<|<|<|<|
|<|*Ширина*|0|columns.0.sparkline.width|Допустимые значения: от 0 до 10.
По умолчанию: 1.
[Поведение параметра](/manual/api/reference_commentary#parameter-behavior):
- *поддерживается*, если *Отображение* установлено в "Спарклайн"|
|^|*Заполнение*|0|columns.0.sparkline.fill|Допустимые значения: от 0 до 10.
По умолчанию: 3.
[Поведение параметра](/manual/api/reference_commentary#parameter-behavior):
- *поддерживается*, если *Отображение* установлено в "Спарклайн"|
|^|*Цвет*|1|columns.0.sparkline.color|Шестнадцатеричный код цвета (например, `FF0000`).
По умолчанию: `42A5F5`.
[Поведение параметра](/manual/api/reference_commentary#parameter-behavior):
- *поддерживается*, если *Отображение* установлено в "Спарклайн"|
|^|*Период времени*|1|columns.0.sparkline.time_period.\_reference|`DASHBOARD._timeperiod` — использовать [селектор периода времени](/manual/web_interface/time_period_selector) панели как источник данных;
`ABCDE._timeperiod` — использовать [совместимый виджет](/manual/web_interface/frontend_sections/dashboards/widgets#widget-compatibility) (с параметром `reference`, равным `ABCDE`) как источник данных.
По умолчанию: `DASHBOARD._timeperiod`
В качестве альтернативы можно задать период времени только в параметрах *От* и *До*.
[Поведение параметра](/manual/api/reference_commentary#parameter-behavior):
- *поддерживается*, если *Отображение* установлено в "Спарклайн"|
|^|*От*|1|columns.0.sparkline.time_period.from|Допустимая строка времени в абсолютном (`YYYY-MM-DD hh:mm:ss`) или [относительном](/manual/web_interface/time_period_selector) формате времени (`now`, `now/d`, `now/w-1w` и т. д.).
[Поведение параметра](/manual/api/reference_commentary#parameter-behavior):
- *поддерживается*, если *Отображение* установлено в "Спарклайн"
- *обязателен*, если задан `columns.0.sparkline.time_period.to`|
|^|*До*|1|columns.0.sparkline.time_period.to|Допустимая строка времени в абсолютном (`YYYY-MM-DD hh:mm:ss`) или [относительном](/manual/web_interface/time_period_selector) формате времени (`now`, `now/d`, `now/w-1w` и т. д.).
[Поведение параметра](/manual/api/reference_commentary#parameter-behavior):
- *поддерживается*, если *Отображение* установлено в "Спарклайн"
- *обязателен*, если задан `columns.0.sparkline.time_period.from`|
|^|*Исторические данные*|0|columns.0.sparkline.history|0 - *(по умолчанию)* Авто;
1 - История;
2 - Тренды.
[Поведение параметра](/manual/api/reference_commentary#parameter-behavior):
- *поддерживается*, если *Отображение* установлено в "Спарклайн"|
|*Пороги*|<|<|<|<|
|<|*Цвет*|1|columns.0.thresholds.0.color|Шестнадцатеричный код цвета (например, `FF0000`).
[Поведение параметра](/manual/api/reference_commentary#parameter-behavior):
- *поддерживается*, если *Отображать значение как* установлено в "Число"|
|^|*Порог*|1|columns.0.thresholds.0.threshold|Любое числовое значение. Поддерживаются [суффиксы](/manual/appendix/suffixes) (например, "1d", "2w", "4K", "8G").
[Поведение параметра](/manual/api/reference_commentary#parameter-behavior):
- *поддерживается*, если *Отображать значение как* установлено в "Число"|
|*Подсветка*|<|<|<|<|
|<|*Подсветка*|1|columns.0.highlights.0.color|Шестнадцатеричный код цвета (например, `FF0000`).
[Поведение параметра](/manual/api/reference_commentary#parameter-behavior):
- *поддерживается*, если *Отображать значение как* установлено в "Текст"|
|^|*Порог*|1|columns.0.highlights.0.pattern|Любое регулярное выражение.
[Поведение параметра](/manual/api/reference_commentary#parameter-behavior):
- *поддерживается*, если *Отображать значение как* установлено в "Текст"|
|*Десятичные знаки*|<|0|columns.0.decimal_places|Допустимые значения: от 0 до 10.
По умолчанию: 2.|
|***Расширенная настройка***|<|<|<|<|
|*Функция агрегации*|<|0|columns.0.aggregate_function|Если *Отображать значение как* установлено в "Число":
0 - *(по умолчанию)* не используется;
1 - min;
2 - max;
3 - avg;
4 - count;
5 - sum;
6 - first;
7 - last.
Если *Отображать значение как* установлено в "Текст":
0 - *(по умолчанию)* не используется;
4 - count;
6 - first;
7 - last.|
|*Период времени*|<|1|columns.0.time_period.\_reference|`DASHBOARD._timeperiod` — использовать [селектор периода времени](/manual/web_interface/time_period_selector) панели как источник данных;
`ABCDE._timeperiod` — использовать [совместимый виджет](/manual/web_interface/frontend_sections/dashboards/widgets#widget-compatibility) (с параметром `reference`, равным `ABCDE`) как источник данных.
По умолчанию: `DASHBOARD._timeperiod`
В качестве альтернативы можно задать период времени только в параметрах *От* и *До*.
[Поведение параметра](/manual/api/reference_commentary#parameter-behavior):
- *поддерживается*, если *Функция агрегации* установлена в "min", "max", "avg", "count", "sum", "first", "last"|
|<|*От*|1|columns.0.time_period.from|Допустимая строка времени в абсолютном (`YYYY-MM-DD hh:mm:ss`) или [относительном](/manual/web_interface/time_period_selector) формате времени (`now`, `now/d`, `now/w-1w` и т. д.).
[Поведение параметра](/manual/api/reference_commentary#parameter-behavior):
- *поддерживается*, если *Период времени* не задан и *Функция агрегации* установлена в "min", "max", "avg", "count", "sum", "first", "last"
- *обязателен*, если задан `columns.0.time_period.to`|
|^|*До*|1|columns.0.time_period.to|Допустимая строка времени в абсолютном (`YYYY-MM-DD hh:mm:ss`) или [относительном](/manual/web_interface/time_period_selector) формате времени (`now`, `now/d`, `now/w-1w` и т. д.).
[Поведение параметра](/manual/api/reference_commentary#parameter-behavior):
- *поддерживается*, если *Период времени* не задан и *Функция агрегации* установлена в "min", "max", "avg", "count", "sum", "first", "last"
- *обязателен*, если задан `columns.0.time_period.from`|
|*Исторические данные*|<|0|columns.0.history|0 - *(по умолчанию)* Авто;
1 - История;
2 - Тренды.
[Поведение параметра](/manual/api/reference_commentary#parameter-behavior):
- *поддерживается*, если *Отображать значение как* установлено в "Число"|
|*Агрегация*|<|0|columns.0.aggregate_columns|0 - *(по умолчанию)* Каждый элемент данных
1 - Объединено.
[Поведение параметра](/manual/api/reference_commentary#parameter-behavior):
- *поддерживается*, если *Отображать значение как* установлено в "Число", а *Отображение* установлено в "Как есть", "Полоса" или "Индикаторы".|
|*Функция объединённой агрегации*|<|0|columns.0.column_aggregate_function|1 - min;
2 - max;
3 - avg;
4 - count;
5 - sum *(по умолчанию)*.
[Поведение параметра](/manual/api/reference_commentary#parameter-behavior):
- *обязателен* при настройке *Агрегации*.|
|*Имя объединённого столбца*|<|1|columns.0.combined_column_name|Любое строковое значение.
[Поведение параметра](/manual/api/reference_commentary#parameter-behavior):
- *обязателен* при настройке *Агрегации*.|
[comment]: # ({/e913fe7b-f35f175e})
[comment]: # ({d54c360f-0700aebf})
### Примеры
Следующие примеры предназначены только для описания настройки объектов полей виджета панели мониторинга для виджета *Top items*.
Для получения дополнительной информации о настройке панели мониторинга см. [`dashboard.create`](/manual/api/reference/dashboard/create).
[comment]: # ({/d54c360f-0700aebf})
[comment]: # ({0ecc438c-03c7c01f})
#### Настройка виджета *Top items*
Настройте виджет *Top items*, который отображает данные для узла сети "10084" и только для тех элементов данных, у которых тег с именем "component" содержит значение "cpu".
Кроме того, отобразите данные так, чтобы узлы сети располагались сверху, и используйте цветную шкалу gauge для представления ячеек.
[Запрос](/manual/api#performing-requests):
```json
{
"jsonrpc": "2.0",
"method": "dashboard.create",
"params": {
"name": "My dashboard",
"display_period": 30,
"auto_start": 1,
"pages": [
{
"widgets": [
{
"type": "topitems",
"name": "Top items",
"x": 0,
"y": 0,
"width": 36,
"height": 5,
"view_mode": 0,
"fields": [
{
"type": 3,
"name": "hostids.0",
"value": 10084
},
{
"type": 1,
"name": "columns.0.items.0",
"value": "*"
},
{
"type": 1,
"name": "columns.0.item_tags.0.tag",
"value": "component"
},
{
"type": 0,
"name": "columns.0.item_tags.0.operator",
"value": 0
},
{
"type": 1,
"name": "columns.0.item_tags.0.value",
"value": "cpu"
},
{
"type": 0,
"name": "columns.0.display",
"value": 2
},
{
"type": 0,
"name": "layout",
"value": 1
}
]
}
]
}
],
"userGroups": [
{
"usrgrpid": 7,
"permission": 2
}
],
"users": [
{
"userid": 1,
"permission": 3
}
]
},
"id": 1
}
```
Ответ:
```json
{
"jsonrpc": "2.0",
"result": {
"dashboardids": [
"3"
]
},
"id": 1
}
```
[comment]: # ({/0ecc438c-03c7c01f})
[comment]: # ({e9d30322-2b7384bb})
### Смотрите также
- [Поле виджета панели](/manual/api/reference/dashboard/object#поле-виджета-панели)
- [`dashboard.create`](/manual/api/reference/dashboard/create)
- [`dashboard.update`](/manual/api/reference/dashboard/update)
[comment]: # ({/e9d30322-2b7384bb})