[comment]: # ({bc57ee5e-e5d5266e})
# 29 トップアイテム
[comment]: # ({/bc57ee5e-e5d5266e})
[comment]: # ({b96fa072-b8507936})
### 説明
これらのパラメータと、各ダッシュボードウィジェットフィールドオブジェクトの可能なプロパティ値により、`dashboard.create`および`dashboard.update`メソッドで[*トップアイテム*](/manual/web_interface/frontend_sections/dashboards/widgets/top_items)ウィジェットを設定できます。
::: noteimportant
ウィジェットの`fields`プロパティは、ダッシュボードの作成または更新時に検証されません。
これにより、ユーザーは[組み込みウィジェット](/manual/web_interface/frontend_sections/dashboards/widgets)を変更したり、[カスタムウィジェット](/devel/modules/tutorials/widget)を作成したりできますが、ウィジェットを誤って作成または更新するリスクも生じます。
*トップアイテム*ウィジェットの作成または更新を確実に行うには、以下の表に記載されているパラメータの動作を参照してください。
:::
[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|[ホストグループ](/manual/api/reference/hostgroup/get) ID。
注: 複数のホストグループを設定するには、各ホストグループごとにプロパティ名の番号を増やしてダッシュボードウィジェットフィールドオブジェクトを作成します。
このパラメータは、[テンプレートダッシュボード](/manual/api/reference/templatedashboard/object)でウィジェットを設定する場合はサポートされません。|
|<|*ホストグループ (ウィジェット)*|1|groupids.\_reference|[ホストグループ](/manual/api/reference/hostgroup/get) IDの代わりに:
`ABCDE._hostgroupids` - *Reference*パラメータを"`ABCDE`"に設定した[互換性のあるウィジェット](/manual/web_interface/frontend_sections/dashboards/widgets#widget-compatibility)をホストグループのデータソースとして設定します。
このパラメータは、[テンプレートダッシュボード](/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` - *Reference*パラメータを"`ABCDE`"に設定した[互換性のあるウィジェット](/manual/web_interface/frontend_sections/dashboards/widgets#widget-compatibility)をホストのデータソースとして設定します。
このパラメータは、[テンプレートダッシュボード](/manual/api/reference/templatedashboard/object)でウィジェットを設定する場合はサポートされません。|
|*ホストタグ*|<|<|<|<|
|<|*評価タイプ*|0|host_tags_evaltype|0 - *(デフォルト)* And/Or;
2 - Or。
このパラメータは、[テンプレートダッシュボード](/manual/api/reference/templatedashboard/object)でウィジェットを設定する場合はサポートされません。|
|^|*タグ名*|1|host_tags.0.tag|任意の文字列値。
注: プロパティ名の番号はタグ評価リスト内のタグ順を参照します。
[パラメータの動作](/manual/api/reference_commentary#parameter-behavior):
- *必須* (*Host tags*を設定する場合)
このパラメータは、[テンプレートダッシュボード](/manual/api/reference/templatedashboard/object)でウィジェットを設定する場合はサポートされません。|
|^|*演算子*|0|host_tags.0.operator|0 - 含む;
1 - 等しい;
2 - 含まない;
3 - 等しくない;
4 - 存在する;
5 - 存在しない。
注: プロパティ名の番号はタグ評価リスト内のタグ順を参照します。
[パラメータの動作](/manual/api/reference_commentary#parameter-behavior):
- *必須* (*Host tags*を設定する場合)
このパラメータは、[テンプレートダッシュボード](/manual/api/reference/templatedashboard/object)でウィジェットを設定する場合はサポートされません。|
|^|*タグ値*|1|host_tags.0.value|任意の文字列値。
注: プロパティ名の番号はタグ評価リスト内のタグ順を参照します。
[パラメータの動作](/manual/api/reference_commentary#parameter-behavior):
- *必須* (*Host tags*を設定する場合)
このパラメータは、[テンプレートダッシュボード](/manual/api/reference/templatedashboard/object)でウィジェットを設定する場合はサポートされません。|
|*レイアウト*|<|0|layout|0 - *(デフォルト)* 横方向;
1 - 縦方向。|
|*障害を表示*|<|0|show_problems|0 - すべて;
1 - *(デフォルト)* 抑制されていない;
2 - なし。|
|*アイテム* (下記参照)|<|<|<|<|
[comment]: # ({/612eaf3d-2a023c70})
[comment]: # ({2cd9fffe-advanced})
#### Advanced configuration
*上位アイテム*ウィジェットでは、以下の詳細設定パラメータがサポートされています。
|パラメータ|<|[type](/manual/api/reference/dashboard/object#dashboard-widget-field)|name|value|
|-|--------|--|--------|--------------------------------------------|
|***ホストの順序***|<|<|<|<|
|*並べ替え*|<|0|host_ordering_order_by|0 - *(default)* ホスト名;
3 - アイテムの値|
|<|*アイテムパターン*|1|host_ordering_item.0|[アイテム](/manual/api/reference/item/get) の名前またはパターン（例："\*: 1 秒あたりに処理される \* 値の数"）
注: 複数のアイテムパターンを設定するには、プロパティ名に増分番号を含む各アイテムパターンのダッシュボードウィジェットフィールドオブジェクトを作成します。
[テンプレートダッシュボード](/manual/api/reference/templatedashboard/object) でウィジェットを設定する場合は、テンプレートで構成されているアイテムのパターンのみを設定する必要があります。
[パラメータの動作](/manual/api/reference_commentary#parameter-behavior):
- *Order by* が "Item value" に設定されている場合、*必須*|
|*Order*|<|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):
- *順序付け* が "Host" に設定されている場合は *必須*|
|*順序*|<|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）は特定のカラムを表し、2つ目の数字（存在する場合）は設定されたエンティティ（例：アイテムパターン、タグ）を表します。
:::
|パラメータ|<|[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"）。
注：複数のアイテムパターンを設定するには、各アイテムパターンごとにプロパティ名の2つ目の数字を増やしてダッシュボードウィジェットフィールドオブジェクトを作成してください。
[テンプレートダッシュボード](/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|任意の文字列値。
注：プロパティ名の2つ目の数字は、タグ評価リスト内のタグの順序を参照します。
[パラメータの動作](/manual/api/reference_commentary#parameter-behavior):
- *アイテムタグ*を設定する場合は*必須*|
|^|*演算子*|0|columns.0.item_tags.0.operator|0 - 含む;
1 - 等しい;
2 - 含まない;
3 - 等しくない;
4 - 存在する;
5 - 存在しない。
注：プロパティ名の2つ目の数字は、タグ評価リスト内のタグの順序を参照します。
[パラメータの動作](/manual/api/reference_commentary#parameter-behavior):
- *アイテムタグ*を設定する場合は*必須*|
|^|*タグ値*|1|columns.0.item_tags.0.value|任意の文字列値。
注：プロパティ名の2つ目の数字は、タグ評価リスト内のタグの順序を参照します。
[パラメータの動作](/manual/api/reference_commentary#parameter-behavior):
- *アイテムタグ*を設定する場合は*必須*|
|*ベースカラー*|<|1|columns.0.base_color|16進数のカラーコード（例：`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|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|columns.0.thresholds.0.color|16進数のカラーコード（例：`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|16進数のカラーコード（例：`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`
または、*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):
- *値の表示形式*が「数値」の場合に*サポート*|
|*集計*|<|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})
#### *トップアイテム* ウィジェットの設定
ホスト"10084"のデータと、名前が"component"のタグに値が"cpu"を含むアイテムのみを表示する *トップアイテム* ウィジェットを設定します。
さらに、ホストを上位に表示し、セルを表すために色付きのゲージバーを使用します。
[リクエスト](/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
}
```
Response:
```json
{
"jsonrpc": "2.0",
"result": {
"dashboardids": [
"3"
]
},
"id": 1
}
```
[comment]: # ({/0ecc438c-03c7c01f})
[comment]: # ({e9d30322-2b7384bb})
### 参照
- [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-2b7384bb})