[comment]: # ({8c8dd5c7-978cbb20})
# 28 热门主机
[comment]: # ({/8c8dd5c7-978cbb20})
[comment]: # ({4e99026f-c5138763})
### 描述
这些参数以及相应仪表板小部件字段对象的可选属性值，可用于在 `dashboard.create` 和 `dashboard.update` 方法中配置 [*Top hosts*](/manual/web_interface/frontend_sections/dashboards/widgets/top_hosts) 小部件。
::: noteimportant
小部件 `fields` 属性在创建或更新仪表板期间不会进行验证。
这使用户能够修改[内置小部件](/manual/web_interface/frontend_sections/dashboards/widgets)并创建[自定义小部件](/devel/modules/tutorials/widget)，但同时也带来了错误创建或更新小部件的风险。
为确保 *Top hosts* 小部件能够成功创建或更新，请参阅下表中列出的参数行为。
:::
[comment]: # ({/4e99026f-c5138763})
[comment]: # ({6c1cb502-224c01f4})
### 参数
以下参数适用于 *Top hosts* 部件。
|参数|<|[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|[主机组](/manual/api/reference/hostgroup/get) ID。
注意：要配置多个主机组，请为每个主机组创建一个 dashboard 部件字段对象，并在属性名称中使用递增的编号。
如果在[模板仪表板](/manual/api/reference/templatedashboard/object)上配置该部件，则不支持此参数。|
|<|*主机组（部件）*|1|groupids.\_reference|用于代替 [主机组](/manual/api/reference/hostgroup/get) ID：
`ABCDE._hostgroupids` - 将[兼容部件](/manual/web_interface/frontend_sections/dashboards/widgets#widget-compatibility)（其 *Reference* 参数设置为 "`ABCDE`"）设置为主机组的数据源。
如果在[模板仪表板](/manual/api/reference/templatedashboard/object)上配置该部件，则不支持此参数。|
|*主机*|<|3|hostids.0|[主机](/manual/api/reference/host/get) ID。
注意：要配置多个主机，请为每个主机创建一个 dashboard 部件字段对象，并在属性名称中使用递增的编号。对于多个主机，参数 *主机组* 要么完全不配置，要么至少配置一个包含所配置主机的主机组。
如果在[模板仪表板](/manual/api/reference/templatedashboard/object)上配置该部件，则不支持此参数。|
|<|*主机（部件/仪表板）*|1|hostids.\_reference|用于代替 [主机](/manual/api/reference/host/get) ID：
`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|evaltype|0 - *(默认)* And/Or；
2 - Or。
如果在[模板仪表板](/manual/api/reference/templatedashboard/object)上配置该部件，则不支持此参数。|
|^|*标签名称*|1|tags.0.tag|任意字符串值。
注意：属性名称中的数字表示标签评估列表中的标签顺序。
[参数行为](/manual/api/reference_commentary#parameter-behavior)：
- 如果配置了 *主机标签*，则为*必填*
如果在[模板仪表板](/manual/api/reference/templatedashboard/object)上配置该部件，则不支持此参数。|
|^|*运算符*|0|tags.0.operator|0 - 包含；
1 - 等于；
2 - 不包含；
3 - 不等于；
4 - 存在；
5 - 不存在。
注意：属性名称中的数字表示标签评估列表中的标签顺序。
[参数行为](/manual/api/reference_commentary#parameter-behavior)：
- 如果配置了 *主机标签*，则为*必填*
如果在[模板仪表板](/manual/api/reference/templatedashboard/object)上配置该部件，则不支持此参数。|
|^|*标签值*|1|tags.0.value|任意字符串值。
注意：属性名称中的数字表示标签评估列表中的标签顺序。
[参数行为](/manual/api/reference_commentary#parameter-behavior)：
- 如果配置了 *主机标签*，则为*必填*
如果在[模板仪表板](/manual/api/reference/templatedashboard/object)上配置该部件，则不支持此参数。|
|*显示维护中的主机*|<|0|maintenance|0 - *(默认)* 禁用；
1 - 启用。|
|*列*（见下文）|<|<|<|<|
|*排序依据*|<|0|column|来自已配置列的列数值。|
|*排序顺序*|<|0|order|2 - *(默认)* Top N；
3 - Bottom N。|
|*主机数量限制*|<|0|show_lines|可能的值范围为 1-1000。
默认值：10。
如果在[模板仪表板](/manual/api/reference/templatedashboard/object)上配置该部件，则不支持此参数。|
[comment]: # ({/6c1cb502-224c01f4})
[comment]: # ({e8e68707-8266fc04})
#### 列
列有公共参数，也有由 *数据* 参数配置确定的额外参数。
::: noteclassic
所有列相关的参数中的数字 (例如：`columns.0.name`) 依赖于配置在哪一列。示例中代表配置第一列。
:::
[comment]: # ({/e8e68707-8266fc04})
[comment]: # ({e35e7f37-bba2be85})
所有列均支持以下参数：
|参数|[类型](/manual/api/reference/dashboard/object#仪表盘组件字段)|参数名称|参数值或参数说明|
|-----|-|-----|-------------------|
|*名称*|1|columns.0.name|任意字符串。
[参数行为](/manual/api/reference_commentary#参数行为)：
- *必需的*。|
|*数据*|0|columns.0.data|1 - 监控项值；
2 - 主机名称；
3 - 文本。
[参数行为](/manual/api/reference_commentary#参数行为)：
- *必需的*。|
|*颜色*|1|columns.0.base_color|十六进制颜色代码(例如：`FF0000`)。
[参数行为](/manual/api/reference_commentary#参数行为)：
- *必需的*。|
[comment]: # ({/e35e7f37-bba2be85})
[comment]: # ({02077e27-5843843c})
##### 监控项值
如果 *Data* 设置为“监控项值”，则支持以下参数。
::: noteclassic
*Thresholds* 属性名称中的第一个数字（例如 columnsthresholds.0.color.0）表示为其配置阈值的列，第二个数字表示按升序排序的列表中的阈值位置。
但是，如果阈值按不同顺序配置，则在 Zabbix 前端中更新部件配置后，这些值将按升序排序（例如，`"threshold.0.threshold":"5"` → `"threshold.0.threshold":"1"`；`"threshold.1.threshold":"1"` → `"threshold.1.threshold": "5"`）。
:::
|参数|<|[type](/manual/api/reference/dashboard/object#dashboard-widget-field)|name|value|
|-|--------|--|--------|-------------------------------|
|*监控项*|<|1 |columns.0.item|有效的监控项名称。
在 [模板仪表板](/manual/api/reference/templatedashboard/object) 上配置该部件时，只应设置模板上已配置的监控项。|
|*将监控项值显示为*|<|0|columns.0.display_value_as|0 - *(默认)* 数值；
1 - 文本；
2 - 二进制。|
|*显示*|<|0|columns.0.display|1 - *(默认)* 按原样；
2 - 条形图；
3 - 指示器；
6 - 迷你图。
[参数行为](/manual/api/reference_commentary#parameter-behavior)：
- 如果 *将监控项值显示为* 设置为“数值”，则 *supported*|
|*最小值*|<|1|columns.0.min|任意数值。
[参数行为](/manual/api/reference_commentary#parameter-behavior)：
- 如果 *将监控项值显示为* 设置为“数值”且 *显示* 设置为“条形图”或“指示器”，则 *supported*|
|*最大值*|<|1|columns.0.max|任意数值。
[参数行为](/manual/api/reference_commentary#parameter-behavior)：
- 如果 *将监控项值显示为* 设置为“数值”且 *显示* 设置为“条形图”或“指示器”，则 *supported*|
|*小数位数*|<|0|columns.0.decimal_places|可能的值范围为 0-10。
默认值：2。
[参数行为](/manual/api/reference_commentary#parameter-behavior)：
- 如果 *将监控项值显示为* 设置为“数值”，则 *supported*|
|*迷你图*|<|<|<|<|
|<|*宽度*|0|columns.0.sparkline.width|可能的值范围为 0-10。
默认值：1。
[参数行为](/manual/api/reference_commentary#parameter-behavior)：
- 如果 *将监控项值显示为* 设置为“数值”且 *显示* 设置为“迷你图”，则 *supported*|
|^|*填充*|0|columns.0.sparkline.fill|可能的值范围为 0-10。
默认值：3。
[参数行为](/manual/api/reference_commentary#parameter-behavior)：
- 如果 *将监控项值显示为* 设置为“数值”且 *显示* 设置为“迷你图”，则 *supported*|
|^|*颜色*|1|columns.0.sparkline.color|十六进制颜色代码（例如 `FF0000`）。
默认值：`42A5F5`。
[参数行为](/manual/api/reference_commentary#parameter-behavior)：
- 如果 *将监控项值显示为* 设置为“数值”且 *显示* 设置为“迷你图”，则 *supported*|
|^|*时间段*|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`
或者，也可以仅在 *From* 和 *To* 参数中设置时间段。
[参数行为](/manual/api/reference_commentary#parameter-behavior)：
- 如果 *将监控项值显示为* 设置为“数值”且 *显示* 设置为“迷你图”，则 *supported*|
|^|*From*|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)：
- 如果 *将监控项值显示为* 设置为“数值”且 *显示* 设置为“迷你图”，则 *supported*
- 如果设置了 `columns.0.sparkline.time_period.to`，则 *required*|
|^|*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)：
- 如果 *将监控项值显示为* 设置为“数值”且 *显示* 设置为“迷你图”，则 *supported*
- 如果设置了 `columns.0.sparkline.time_period.from`，则 *required*|
|^|*历史数据*|0|columns.0.sparkline.history|0 - *(默认)* 自动；
1 - 历史；
2 - 趋势。
[参数行为](/manual/api/reference_commentary#parameter-behavior)：
- 如果 *将监控项值显示为* 设置为“数值”且 *显示* 设置为“迷你图”，则 *supported*|
|*阈值*|<|<|<|<|
|<|*颜色*|1|columnsthresholds.0.color.0|十六进制颜色代码（例如 `FF0000`）。
[参数行为](/manual/api/reference_commentary#parameter-behavior)：
- 如果 *将监控项值显示为* 设置为“数值”，则 *supported*|
|^|*阈值*|1|columnsthresholds.0.threshold.0|任意字符串值。
[参数行为](/manual/api/reference_commentary#parameter-behavior)：
- 如果 *将监控项值显示为* 设置为“数值”，则 *supported*|
|*高亮*|<|<|<|<|
|<|*颜色*|1|columns.0.highlights.0.color|十六进制颜色代码（例如 `FF0000`）。
[参数行为](/manual/api/reference_commentary#parameter-behavior)：
- 如果 *将监控项值显示为* 设置为“文本”，则 *supported*|
|^|*模式*|1|columns.0.highlights.0.pattern|任意字符串值。
[参数行为](/manual/api/reference_commentary#parameter-behavior)：
- 如果 *将监控项值显示为* 设置为“文本”，则 *supported*|
|*显示缩略图*|<|0|columns.0.show_thumbnail|0 - *(默认)* 禁用；
1 - 启用。
[参数行为](/manual/api/reference_commentary#parameter-behavior)：
- 如果 *将监控项值显示为* 设置为“二进制”，则 *supported*|
|*聚合函数*|<|0|columns.0.aggregate_function|0 - *(默认)* 不使用；
1 - min；
2 - max；
3 - avg；
4 - count；
5 - sum；
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`
或者，也可以仅在 *From* 和 *To* 参数中设置时间段。
[参数行为](/manual/api/reference_commentary#parameter-behavior)：
- 如果 *Aggregation function* 设置为 “min”、“max”、“avg”、“count”、“sum”、“first”、“last”，则 *supported*|
|<|*From*|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)：
- 如果未设置 *Time period* 且 *Aggregation function* 设置为 “min”、“max”、“avg”、“count”、“sum”、“first”、“last”，则 *supported*
- 如果设置了 `columns.0.time_period.to`，则 *required*|
|^|*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)：
- 如果未设置 *Time period* 且 *Aggregation function* 设置为 “min”、“max”、“avg”、“count”、“sum”、“first”、“last”，则 *supported*
- 如果设置了 `columns.0.time_period.from`，则 *required*|
|*历史数据*|<|0|columns.0.history|0 - *(默认)* 自动；
1 - 历史；
2 - 趋势。
[参数行为](/manual/api/reference_commentary#parameter-behavior)：
- 如果 *将监控项值显示为* 设置为“数值”，则 *supported*|
|*引用*|<|1|reference|由 5 个字符组成的任意字符串值（例如 `ABCDE` 或 `JBPNL`）。该值在该部件所属的仪表板内必须唯一。
[参数行为](/manual/api/reference_commentary#parameter-behavior)：
- *required*|
[comment]: # ({/02077e27-5843843c})
[comment]: # ({55d0acdb-18fd738d})
##### 文本
当 *数据* 设置为 "文本" 时，支持以下参数：
|参数|[类型](/manual/api/reference/dashboard/object#仪表盘组件字段)|参数名称|参数值或参数说明|
|-----|-|-----|-------------------|
|*文本*|1|columns.0.text|任意字符串，包含宏变量。
支持的宏变量如下：{HOST.\*}、{INVENTORY.\*}。
[参数行为](/manual/api/reference_commentary#参数行为)：
- *必需的* (如果 *数据* 设置为 "文本")。|
[comment]: # ({/55d0acdb-18fd738d})
[comment]: # ({e7eaa526-c274247c})
### 示例
以下示例仅用于介绍如何在仪表盘组件字段对象中配置 *Top主机* 组件。
更多信息，请参考 [创建仪表盘](/manual/api/reference/dashboard/create)。
[comment]: # ({/e7eaa526-c274247c})
[comment]: # ({ec72cf7d-2e9b79c3})
#### 配置一个*Top主机*组件
配置一个*Top主机*组件，用于展示主机组 "4" 中 CPU 利用率的 Top 主机。
同时配置如下列："Host name", "CPU utilization in %", "1m avg", "5m avg", "15m avg", "Processes"。
[请求](/manual/api#执行请求):
```json
{
"jsonrpc": "2.0",
"method": "dashboard.create",
"params": {
"name": "My dashboard",
"display_period": 30,
"auto_start": 1,
"pages": [
{
"widgets": [
{
"type": "tophosts",
"name": "Top hosts",
"x": 0,
"y": 0,
"width": 36,
"height": 5,
"view_mode": 0,
"fields": [
{
"type": 2,
"name": "groupids.0",
"value": 4
},
{
"type": 1,
"name": "columns.0.name",
"value": "Host"
},
{
"type": 0,
"name": "columns.0.data",
"value": 2
},
{
"type": 1,
"name": "columns.0.base_color",
"value": "FFFFFF"
},
{
"type": 1,
"name": "columns.1.name",
"value": "CPU utilization in %"
},
{
"type": 0,
"name": "columns.1.data",
"value": 1
},
{
"type": 1,
"name": "columns.1.base_color",
"value": "4CAF50"
},
{
"type": 1,
"name": "columns.1.item",
"value": "CPU utilization"
},
{
"type": 0,
"name": "columns.1.display",
"value": 3
},
{
"type": 1,
"name": "columns.1.min",
"value": "0"
},
{
"type": 1,
"name": "columns.1.max",
"value": "100"
},
{
"type": 1,
"name": "columnsthresholds.1.color.0",
"value": "FFFF00"
},
{
"type": 1,
"name": "columnsthresholds.1.threshold.0",
"value": "50"
},
{
"type": 1,
"name": "columnsthresholds.1.color.1",
"value": "FF8000"
},
{
"type": 1,
"name": "columnsthresholds.1.threshold.1",
"value": "80"
},
{
"type": 1,
"name": "columnsthresholds.1.color.2",
"value": "FF4000"
},
{
"type": 1,
"name": "columnsthresholds.1.threshold.2",
"value": "90"
},
{
"type": 1,
"name": "columns.2.name",
"value": "1m avg"
},
{
"type": 0,
"name": "columns.2.data",
"value": 1
},
{
"type": 1,
"name": "columns.2.base_color",
"value": "FFFFFF"
},
{
"type": 1,
"name": "columns.2.item",
"value": "Load average (1m avg)"
},
{
"type": 1,
"name": "columns.3.name",
"value": "5m avg"
},
{
"type": 0,
"name": "columns.3.data",
"value": 1
},
{
"type": 1,
"name": "columns.3.base_color",
"value": "FFFFFF"
},
{
"type": 1,
"name": "columns.3.item",
"value": "Load average (5m avg)"
},
{
"type": 1,
"name": "columns.4.name",
"value": "15m avg"
},
{
"type": 0,
"name": "columns.4.data",
"value": 1
},
{
"type": 1,
"name": "columns.4.base_color",
"value": "FFFFFF"
},
{
"type": 1,
"name": "columns.4.item",
"value": "Load average (15m avg)"
},
{
"type": 1,
"name": "columns.5.name",
"value": "Processes"
},
{
"type": 0,
"name": "columns.5.data",
"value": 1
},
{
"type": 1,
"name": "columns.5.base_color",
"value": "FFFFFF"
},
{
"type": 1,
"name": "columns.5.item",
"value": "Number of processes"
},
{
"type": 0,
"name": "columns.5.decimal_places",
"value": 0
},
{
"type": 0,
"name": "column",
"value": 1
}
]
}
]
}
],
"userGroups": [
{
"usrgrpid": 7,
"permission": 2
}
],
"users": [
{
"userid": 1,
"permission": 3
}
]
},
"id": 1
}
```
响应：
```json
{
"jsonrpc": "2.0",
"result": {
"dashboardids": [
"3"
]
},
"id": 1
}
```
[comment]: # ({/ec72cf7d-2e9b79c3})
[comment]: # ({e9d30322-d8c32fe2})
### 参考
- [仪表盘组件字段](/manual/api/reference/dashboard/object#仪表盘组件字段)
- [创建仪表盘](/manual/api/reference/dashboard/create)
- [更新仪表盘](/manual/api/reference/dashboard/update)
[comment]: # ({/e9d30322-d8c32fe2})