[comment]: # ({8c8dd5c7-978cbb20})
# 28 トップホスト
[comment]: # ({/8c8dd5c7-978cbb20})
[comment]: # ({4e99026f-c5138763})
### 説明
これらのパラメータと各ダッシュボードウィジェットフィールドオブジェクトの可能なプロパティ値により、`dashboard.create`および`dashboard.update`メソッドで[*トップホスト*](/manual/web_interface/frontend_sections/dashboards/widgets/top_hosts)ウィジェットを設定できます。
::: noteimportant
ウィジェットの`fields`プロパティは、ダッシュボードの作成または更新時にバリデーションされません。
これにより、ユーザーは[組み込みウィジェット](/manual/web_interface/frontend_sections/dashboards/widgets)を変更したり、[カスタムウィジェット](/devel/modules/tutorials/widget)を作成したりできますが、ウィジェットを誤って作成または更新するリスクも生じます。
*トップホスト*ウィジェットの作成または更新を確実に行うには、以下の表に記載されているパラメータの動作を参照してください。
:::
[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。
注: 複数のホストグループを設定するには、各ホストグループごとにプロパティ名の番号を増やしてダッシュボードウィジェットフィールドオブジェクトを作成します。
このパラメータは、[テンプレートダッシュボード](/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。
注: 複数のホストを設定するには、各ホストごとにプロパティ名の番号を増やしてダッシュボードウィジェットフィールドオブジェクトを作成します。複数のホストを指定する場合、*ホストグループ*パラメータは未設定、または指定したホストが属するホストグループが少なくとも1つ設定されている必要があります。
このパラメータは、[テンプレートダッシュボード](/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})
以下のパラメーターはすべての列でサポートされています。
|パラメーター|[type](/manual/api/reference/dashboard/object#dashboard-widget-field)|name|value|
|-----|-|-----|-------------------|
|*Name*|1|columns.0.name|任意の文字列値
[パラメーターの動作](/manual/api/reference_commentary#parameter-behavior):
- *必須*|
|*Data*|0|columns.0.data|1 - 項目値
2 - ホスト名
3 - テキスト
[パラメーターの動作](/manual/api/reference_commentary#parameter-behavior):
- *必須*|
|*基本色*|1|columns.0.base_color|16進数カラーコード（例：`FF0000`）
[パラメータの動作](/manual/api/reference_commentary#parameter-behavior):
- *必須*|
[comment]: # ({/e35e7f37-bba2be85})
[comment]: # ({02077e27-5843843c})
##### アイテム値
*Data*が「アイテム値」に設定されている場合、以下のパラメータがサポートされます。
::: noteclassic
*Thresholds*プロパティ名の最初の数字(例: columnsthresholds.0.color.0)は、しきい値が設定されている列を参照し、2番目の数字は昇順で並べ替えられたリスト内のしきい値の位置を参照します。
ただし、しきい値が異なる順序で設定されている場合、Zabbix Webインターフェースでウィジェットの設定を更新した後、値は昇順に並べ替えられます(例: `"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):
- *アイテム値の表示形式*が「数値」の場合に*サポート*|
|*最小値*|<|1|columns.0.min|任意の数値。
[パラメータの動作](/manual/api/reference_commentary#parameter-behavior):
- *アイテム値の表示形式*が「数値」かつ*表示*が「バー」または「インジケーター」の場合に*サポート*|
|*最大値*|<|1|columns.0.max|任意の数値。
[パラメータの動作](/manual/api/reference_commentary#parameter-behavior):
- *アイテム値の表示形式*が「数値」かつ*表示*が「バー」または「インジケーター」の場合に*サポート*|
|*小数点以下の桁数*|<|0|columns.0.decimal_places|0-10の範囲で指定可能。
デフォルト: 2。
[パラメータの動作](/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|16進数のカラーコード(例: `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`
または、*From*および*To*パラメータで期間のみを設定することもできます。
[パラメータの動作](/manual/api/reference_commentary#parameter-behavior):
- *アイテム値の表示形式*が「数値」かつ*表示*が「スパークライン」の場合に*サポート*|
|^|*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):
- *アイテム値の表示形式*が「数値」かつ*表示*が「スパークライン」の場合に*サポート*
- `columns.0.sparkline.time_period.to`が設定されている場合は*必須*|
|^|*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|columnsthresholds.0.color.0|16進数のカラーコード(例: `FF0000`)。
[パラメータの動作](/manual/api/reference_commentary#parameter-behavior):
- *アイテム値の表示形式*が「数値」の場合に*サポート*|
|^|*しきい値*|1|columnsthresholds.0.threshold.0|任意の文字列。
[パラメータの動作](/manual/api/reference_commentary#parameter-behavior):
- *アイテム値の表示形式*が「数値」の場合に*サポート*|
|*ハイライト*|<|<|<|<|
|<|*色*|1|columns.0.highlights.0.color|16進数のカラーコード(例: `FF0000`)。
[パラメータの動作](/manual/api/reference_commentary#parameter-behavior):
- *アイテム値の表示形式*が「テキスト」の場合に*サポート*|
|^|*パターン*|1|columns.0.highlights.0.pattern|任意の文字列。
[パラメータの動作](/manual/api/reference_commentary#parameter-behavior):
- *アイテム値の表示形式*が「テキスト」の場合に*サポート*|
|*サムネイルの表示*|<|0|columns.0.show_thumbnail|0 - *(デフォルト)* 無効;
1 - 有効。
[パラメータの動作](/manual/api/reference_commentary#parameter-behavior):
- *アイテム値の表示形式*が「バイナリ」の場合に*サポート*|
|*集計関数*|<|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):
- *集計関数*が「min」「max」「avg」「count」「sum」「first」「last」の場合に*サポート*|
|<|*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):
- *期間*が設定されておらず、*集計関数*が「min」「max」「avg」「count」「sum」「first」「last」の場合に*サポート*
- `columns.0.time_period.to`が設定されている場合は*必須*|
|^|*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):
- *アイテム値の表示形式*が「数値」の場合に*サポート*|
|*参照*|<|1|reference|5文字からなる任意の文字列(例: `ABCDE`または`JBPNL`)。この値は、ウィジェットが属するダッシュボード内で一意である必要があります。
[パラメータの動作](/manual/api/reference_commentary#parameter-behavior):
- *必須*|
[comment]: # ({/02077e27-5843843c})
[comment]: # ({55d0acdb-18fd738d})
##### Text
*データ*が"テキスト"に設定されている場合、以下のパラメーターがサポートされます。
|パラメーター|[type](/manual/api/reference/dashboard/object#dashboard-widget-field)|name|value|
|-----|-|-----|-------------------|
|*テキスト*|1|columns.0.text|マクロを含む任意の文字列値
サポートされているマクロ: {HOST.\*}、{INVENTORY.\*}
[パラメーターの動作](/manual/api/reference_commentary#parameter-behavior):
- *データ*がテキスト"に設定されている場合、*必須*|
[comment]: # ({/55d0acdb-18fd738d})
[comment]: # ({e7eaa526-c274247c})
### 例
次の例は、*上位ホスト*ウィジェットのダッシュボードウィジェットフィールドオブジェクトの設定を説明することだけを目的としています。
ダッシュボードの設定の詳細については、[`dashboard.create`](/manual/api/reference/dashboard/create)を参照してください。
[comment]: # ({/e7eaa526-c274247c})
[comment]: # ({ec72cf7d-2e9b79c3})
#### *上位ホスト*ウィジェットの設定
ホストグループ"4"でCPU使用率上位のホストを表示する*上位ホスト*ウィジェットを構成します。
さらに、次のカスタム列を構成します: "Host name", "CPU utilization in %", "1m avg", "5m avg", "15m avg", "Processes"。
[リクエスト](/manual/api#performing-requests):
```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})
### 参照
- [Dashboard widget field](/manual/api/reference/dashboard/object#dashboard-widget-field)
- [`dashboard.create`](/manual/api/reference/dashboard/create)
- [`dashboard.update`](/manual/api/reference/dashboard/update)
[comment]: # ({/e9d30322-d8c32fe2})