[comment]: # ({3bc2905a-a139f9f9})
# 18 アイテム値
[comment]: # ({/3bc2905a-a139f9f9})
[comment]: # ({ea9944d9-b003922b})
### 説明
これらのパラメータと各ダッシュボードウィジェットフィールドオブジェクトの可能なプロパティ値により、`dashboard.create`および`dashboard.update`メソッドで[*アイテム値*](/manual/web_interface/frontend_sections/dashboards/widgets/item_value)ウィジェットを設定できます。
::: noteimportant
ウィジェットの`fields`プロパティは、ダッシュボードの作成または更新時に検証されません。
これにより、ユーザーは[組み込みウィジェット](/manual/web_interface/frontend_sections/dashboards/widgets)を変更したり、[カスタムウィジェット](/devel/modules/tutorials/widget)を作成したりできますが、ウィジェットを誤って作成または更新するリスクも生じます。
*アイテム値*ウィジェットの作成または更新を確実に行うには、以下の表に記載されているパラメータの動作を参照してください。
:::
[comment]: # ({/ea9944d9-b003922b})
[comment]: # ({ff37091c-2afe65e8})
### パラメータ
以下のパラメータは *Item value* ウィジェットでサポートされています。
|Parameter|<|[type](/manual/api/reference/dashboard/object#dashboard-widget-field)|name|value|
|-|-----|-|-----|-------------------|
|*Refresh interval*|<|0|rf_rate|0 - 更新しない;
10 - 10秒;
30 - 30秒;
60 - *(default)* 1分;
120 - 2分;
600 - 10分;
900 - 15分。|
|*Item*|<|4|itemid.0|[アイテム](/manual/api/reference/item/get) ID。
[Parameter behavior](/manual/api/reference_commentary#parameter-behavior):
- *required* if *Item (Widget)* is not set|
|<|*Item (Widget)*|1|itemid.\_reference|[アイテム](/manual/api/reference/item/get) ID の代わりに:
`ABCDE._itemid` - [互換性のあるウィジェット](/manual/web_interface/frontend_sections/dashboards/widgets#widget-compatibility)（*Reference* パラメータが "`ABCDE`" に設定されているもの）を、アイテムのデータソースとして設定します。
[Parameter behavior](/manual/api/reference_commentary#parameter-behavior):
- *required* if *Item* is not set|
|*Show*|<|0|show.0|1 - 説明;
2 - 値;
3 - 時刻;
4 - 変化インジケーター;
5 - スパークライン。
Default: 1, 2, 3, 4.
Note: 複数の値を設定するには、各値ごとに dashboard widget field オブジェクトを作成し、property name の番号を増やしてください。|
|*Override host*|<|1|override_hostid.\_reference|`ABCDE._hostid` - [互換性のあるウィジェット](/manual/web_interface/frontend_sections/dashboards/widgets#widget-compatibility)（*Reference* パラメータが "`ABCDE`" に設定されているもの）を、ホストのデータソースとして設定します;
`DASHBOARD._hostid` - ダッシュボードの [*Host* セレクター](/manual/web_interface/frontend_sections/dashboards/widgets#override-host) をホストのデータソースとして設定します。
このパラメータは、[テンプレートダッシュボード](/manual/api/reference/templatedashboard/object) 上でウィジェットを設定する場合はサポートされません。|
[comment]: # ({/ff37091c-2afe65e8})
[comment]: # ({c697bfd0-3cc5f221})
#### 詳細設定
以下の詳細設定パラメータは、*アイテム値* ウィジェットでサポートされています。
::: noteclassic
*Thresholds* プロパティ名の数字（例: thresholds.0.color）は、昇順に並べられたリスト内でのしきい値の位置を参照します。
ただし、しきい値が別の順序で設定されている場合、Zabbix Webインターフェースでウィジェット設定を更新した後に、値は昇順に並べ替えられます（例: `"thresholds.0.threshold":"5"` → `"thresholds.0.threshold":"1"`; `"thresholds.1.threshold":"1"` → `"thresholds.1.threshold": "5"`）。
:::
|Parameter|<|[type](/manual/api/reference/dashboard/object#dashboard-widget-field)|name|value|
|-|--------|--|--------|-------------------------------|
|*Background color*|<|1|bg_color|16進カラーコード（例: `FF0000`）。
デフォルト: `""`（空）。|
|*Thresholds*|<|<|<|<|
|<|*Color*|1|thresholds.0.color|16進カラーコード（例: `FF0000`）。|
|^|*Threshold*|1|thresholds.0.threshold|任意の文字列値。|
|*Aggregation function*|<|0|aggregate_function|0 - *(デフォルト)* 未使用;
1 - 最小;
2 - 最大;
3 - 平均;
4 - 件数;
5 - 合計;
6 - 最初;
7 - 最後。|
|*Time period*|<|1|time_period.\_reference|`DASHBOARD._timeperiod` - [*Time period* セレクター](/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|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*
- `time_period.to` が設定されている場合に *required*|
|^|*To*|1|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*
- `time_period.from` が設定されている場合に *required*|
|*History data*|<|0|history|0 - *(デフォルト)* 自動;
1 - 履歴;
2 - トレンド。|
[comment]: # ({/c697bfd0-3cc5f221})
[comment]: # ({bcaa25cb-1925c46d})
##### Description
*表示*が"説明"に設定されている場合、以下の詳細設定パラメータがサポートされます。
|パラメータ|[type](/manual/api/reference/dashboard/object#dashboard-widget-field)|名前|値|
|-----|-|-----|-------------------|
|*説明*|1|説明|マクロを含む任意の文字列値
サポートされているマクロ: {HOST.\*}、{ITEM.\*}、{INVENTORY.\*}、ユーザーマクロ
デフォルト: {ITEM.NAME}|
|*水平位置*|0|desc_h_pos|0 - 左
1 - *(デフォルト)* 中央
2 - 右
2つ以上の要素 (説明、値、時間) で同じ *水平位置* と *垂直位置* を共有することはできません。|
|*垂直位置*|0|desc_v_pos|0 - 上;
1 - 中央;
2 - *(デフォルト)* 下
2 つ以上の要素 (説明、値、時刻) が同じ *水平位置* と *垂直位置* を共有することはできません。|
|*サイズ*|0|desc_size|指定可能な値の範囲は 1～100 です。
デフォルト: 15|
|*太字*|0|desc_bold|0 - *(デフォルト)* 無効;
1 - 有効|
|*色*|1|desc_color|16 進数のカラーコード (例: `FF0000`)
デフォルト: `""` (空)|
[comment]: # ({/bcaa25cb-1925c46d})
[comment]: # ({f2dff83b-9657b88c})
##### Value
*表示*が"値"に設定されている場合、以下の詳細設定パラメータがサポートされます。
|パラメータ|<|[type](/manual/api/reference/dashboard/object#dashboard-widget-field)|名前|値|
|-|--------|--|--------|--------------------------------------------|
|*小数点以下の桁数*|<|<|<|<|
|<|*小数点以下の桁数*|0|decimal_places|有効な値の範囲は1～10です。
デフォルト: 2|
|^|*サイズ*|0|decimal_size|有効な値の範囲は1～100です。
デフォルト: 35|
|*位置*|<|<|<|<|
|<|*水平位置*|0|value_h_pos|0 - 左;
1 - *(デフォルト)* 中央;
2 - 右
2 つ以上の要素 (説明、値、時間) が同じ *水平位置* と *垂直位置* を共有することはできません。|
|^|*垂直位置*|0|value_v_pos|0 - 上;
1 - *(デフォルト)* 中央;
2 - 下
2 つ以上の要素 (説明、値、時間) が同じ *水平位置* と *垂直位置* を共有することはできません。|
|^|*サイズ*|0|value_size|有効な値の範囲は 1～100 です。
デフォルト: 45|
|^|*太字*|0|value_bold|0 - 無効;
1 - *(デフォルト)* 有効|
|^|*色*|1|値_色|16進数のカラーコード（例：`FF0000`）
デフォルト：`""`（空）|
|*単位*|<|<|<|<|
|<|*単位*（チェックボックス）|0|単位表示|0 - 無効
1 - *（デフォルト）* 有効|
|^|*単位*（値）|1|単位|任意の文字列値|
|^|*位置*|0|単位_位置|0 - 前の値
1 - 上の値
2 - *（デフォルト）* 後の値
3 - 下の値|
|^|*サイズ*|0|単位_サイズ|可能な値の範囲は1～100です。
デフォルト：35|
|^|*太字*|0|units_bold|0 - 無効;
1 - *(デフォルト)* 有効|
|^|*色*|1|units_color|16進数の色コード (例: `FF0000`)
デフォルト: `""` (空)|
[comment]: # ({/f2dff83b-9657b88c})
[comment]: # ({3e71dbcf-c0007d65})
##### 時間
*表示*が"時間"に設定されている場合、以下の詳細設定パラメータがサポートされます。
|パラメータ|[type](/manual/api/reference/dashboard/object#dashboard-widget-field)|名前|値|
|-----|-|-----|-------------------|
|*水平位置*|0|time_h_pos|0 - 左;
1 - *(デフォルト)* 中央;
2 - 右
2つ以上の要素（説明、値、時間）が同じ*水平位置*と*垂直位置*を共有することはできません。|
|*垂直位置*|0|time_v_pos|0 - *(デフォルト)* 上;
1 - 中央;
2 - 下
2つ以上の要素（説明、値、時間）が同じ*水平位置*と*垂直位置*を共有することはできません。|
|*サイズ*|0|time_size|指定可能な値の範囲は1～100です。
デフォルト: 15|
|*太字*|0|time_bold|0 - *(デフォルト)* 無効
1 - 有効|
|*色*|1|time_color|16進数のカラーコード(例: `FF0000`)
デフォルト: `""` (空)|
[comment]: # ({/3e71dbcf-c0007d65})
[comment]: # ({2fbaf324-f824a1aa})
##### 変更インジケーター
*表示*が"変更インジケーター"に設定されている場合、以下の詳細設定パラメータがサポートされます。
|パラメータ|[type](/manual/api/reference/dashboard/object#dashboard-widget-field)|名前|値|
|-----|-|-----|-------------------|
|*変更インジケーター↑の色*|1|up_color|16進数カラーコード（例：`FF0000`）
デフォルト：`""`（空）|
|*変更インジケーター↓の色*|1|down_color|16進数カラーコード（例：`FF0000`）
デフォルト：`""`（空）|
|*インジケーターの色変更*|1|updown_color|16進数カラーコード（例：`FF0000`）
デフォルト：`""`（空）|
[comment]: # ({/2fbaf324-f824a1aa})
[comment]: # ({7f4e167c-7929c294})
##### スパークライン
以下の高度な設定パラメータは、*Show* が "Sparkline" に設定されている場合にサポートされます。
|Parameter|<|[type](/manual/api/reference/dashboard/object#dashboard-widget-field)|name|value|
|-|--------|--|--------|-------------------------------|
|*Width*|<|0|sparkline.width|指定可能な値の範囲は 0-10 です。
デフォルト: 1.|
|*Fill*|<|0|sparkline.fill|指定可能な値の範囲は 0-10 です。
デフォルト: 3.|
|*Color*|<|1|sparkline.color|16進数のカラーコード（例: `FF0000`）。
デフォルト: `42A5F5`.|
|*Time period*|<|1|sparkline.time_period.\_reference|`DASHBOARD._timeperiod` - [*Time period* セレクター](/manual/web_interface/time_period_selector) をデータソースとして設定します。
`ABCDE._timeperiod` - [互換性のあるウィジェット](/manual/web_interface/frontend_sections/dashboards/widgets#widget-compatibility)（`reference` パラメータが `ABCDE` と等しいもの）をデータソースとして設定します。
デフォルト: `DASHBOARD._timeperiod`
または、時間範囲を *From* と *To* パラメータのみで設定することもできます。|
|<|*From*|1|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):
- `sparkline.time_period.to` が設定されている場合は *required*|
|^|*To*|1|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):
- `sparkline.time_period.from` が設定されている場合は *required*|
|*History data*|<|0|sparkline.history|0 - *(default)* 自動;
1 - 履歴;
2 - トレンド.|
[comment]: # ({/7f4e167c-7929c294})
[comment]: # ({fd9ac7eb-7c28c6ce})
### 例
次の例は、*アイテムの値*ウィジェットのダッシュボードウィジェットフィールドオブジェクトの設定を説明することだけを目的としています。
ダッシュボードの設定の詳細については、[`dashboard.create`](/manual/api/reference/dashboard/create)を参照してください。
[comment]: # ({/fd9ac7eb-7c28c6ce})
[comment]: # ({61d2e13d-e1b71728})
#### *アイテムの値*ウィジェットの設定
アイテム"42266"(Zabbixエージェントの可用性)のアイテム値を表示する*アイテムの値*ウィジェットを設定します。さらにウィジェットを複数の詳細オプションを使用して、Zabbixエージェントの可用性ステータスに基づいて変更される動的な背景色といった視覚的な調整をします。
[リクエスト](/manual/api#performing-requests):
```json
{
"jsonrpc": "2.0",
"method": "dashboard.create",
"params": {
"name": "My dashboard",
"display_period": 30,
"auto_start": 1,
"pages": [
{
"widgets": [
{
"type": "item",
"name": "Item value",
"x": 0,
"y": 0,
"width": 12,
"height": 3,
"view_mode": 0,
"fields": [
{
"type": 4,
"name": "itemid.0",
"value": 42266
},
{
"type": 0,
"name": "show.0",
"value": 1
},
{
"type": 0,
"name": "show.1",
"value": 2
},
{
"type": 0,
"name": "show.2",
"value": 3
},
{
"type": 1,
"name": "description",
"value": "Agent status"
},
{
"type": 0,
"name": "desc_h_pos",
"value": 0
},
{
"type": 0,
"name": "desc_v_pos",
"value": 0
},
{
"type": 0,
"name": "desc_bold",
"value": 1
},
{
"type": 1,
"name": "desc_color",
"value": "F06291"
},
{
"type": 0,
"name": "value_h_pos",
"value": 0
},
{
"type": 0,
"name": "value_size",
"value": 25
},
{
"type": 1,
"name": "value_color",
"value": "FFFF00"
},
{
"type": 0,
"name": "units_show",
"value": 0
},
{
"type": 0,
"name": "time_h_pos",
"value": 2
},
{
"type": 0,
"name": "time_v_pos",
"value": 2
},
{
"type": 0,
"name": "time_size",
"value": 10
},
{
"type": 0,
"name": "time_bold",
"value": 1
},
{
"type": 1,
"name": "time_color",
"value": "9FA8DA"
},
{
"type": 1,
"name": "thresholds.0.color",
"value": "E1E1E1"
},
{
"type": 1,
"name": "thresholds.0.threshold",
"value": "0"
},
{
"type": 1,
"name": "thresholds.1.color",
"value": "D1C4E9"
},
{
"type": 1,
"name": "thresholds.1.threshold",
"value": "1"
}
]
}
]
}
],
"userGroups": [
{
"usrgrpid": 7,
"permission": 2
}
],
"users": [
{
"userid": 1,
"permission": 3
}
]
},
"id": 1
}
```
レスポンス:
```json
{
"jsonrpc": "2.0",
"result": {
"dashboardids": [
"3"
]
},
"id": 1
}
```
[comment]: # ({/61d2e13d-e1b71728})
[comment]: # ({e9d30322-d0066a0f})
### 参照
- [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-d0066a0f})