[comment]: # ({3bc2905a-a139f9f9})
# 18 Valor do item
[comment]: # ({/3bc2905a-a139f9f9})
[comment]: # ({ea9944d9-b003922b})
### Descrição
Esses parâmetros e os possíveis valores de propriedade para os respectivos objetos de campo do widget do dashboard permitem configurar o widget [*Valor do item*](/manual/web_interface/frontend_sections/dashboards/widgets/item_value) nos métodos `dashboard.create` e `dashboard.update`.
::: noteimportant
As propriedades `fields` do widget não são validadas durante a criação ou atualização de um dashboard.
Isso permite que os usuários modifiquem [widgets internos](/manual/web_interface/frontend_sections/dashboards/widgets) e criem [widgets personalizados](/devel/modules/tutorials/widget), mas também introduz o risco de criar ou atualizar widgets incorretamente.
Para garantir a criação ou atualização bem-sucedida do widget *Valor do item*, consulte o comportamento dos parâmetros descrito nas tabelas abaixo.
:::
[comment]: # ({/ea9944d9-b003922b})
[comment]: # ({ff37091c-2afe65e8})
### Parâmetros
Os seguintes parâmetros são suportados para o widget *Item value*.
|Parameter|<|[type](/manual/api/reference/dashboard/object#dashboard-widget-field)|name|value|
|-|-----|-|-----|
|*Refresh interval*|<|0|rf_rate|0 - Sem atualização;
10 - 10 segundos;
30 - 30 segundos;
60 - *(padrão)* 1 minuto;
120 - 2 minutos;
600 - 10 minutos;
900 - 15 minutos.|
|*Item*|<|4|itemid.0|ID do [Item](/manual/api/reference/item/get).
[Comportamento do parâmetro](/manual/api/reference_commentary#parameter-behavior):
- *obrigatório* se *Item (Widget)* não estiver definido|
|<|*Item (Widget)*|1|itemid.\_reference|Em vez do ID do [Item](/manual/api/reference/item/get):
`ABCDE._itemid` - defina um [widget compatível](/manual/web_interface/frontend_sections/dashboards/widgets#widget-compatibility) (com o parâmetro *Reference* definido como "`ABCDE`") como a fonte de dados para itens.
[Comportamento do parâmetro](/manual/api/reference_commentary#parameter-behavior):
- *obrigatório* se *Item* não estiver definido|
|*Show*|<|0|show.0|1 - Descrição;
2 - Valor;
3 - Hora;
4 - Indicador de alteração;
5 - Sparkline.
Padrão: 1, 2, 3, 4.
Observação: para configurar vários valores, crie um objeto de campo do widget do dashboard para cada valor, com um número incrementado no nome da propriedade.|
|*Override host*|<|1|override_hostid.\_reference|`ABCDE._hostid` - defina um [widget compatível](/manual/web_interface/frontend_sections/dashboards/widgets#widget-compatibility) (com o parâmetro *Reference* definido como "`ABCDE`") como a fonte de dados para hosts;
`DASHBOARD._hostid` - defina o [seletor *Host*](/manual/web_interface/frontend_sections/dashboards/widgets#override-host) do dashboard como a fonte de dados para hosts.
Este parâmetro não é suportado ao configurar o widget em um [template dashboard](/manual/api/reference/templatedashboard/object).|
[comment]: # ({/ff37091c-2afe65e8})
[comment]: # ({c697bfd0-3cc5f221})
#### Configuração avançada
Os seguintes parâmetros de configuração avançada são suportados para o widget *Item value*.
::: noteclassic
O número no nome da propriedade *Thresholds* (por exemplo, thresholds.0.color) faz referência à posição do threshold em uma lista, classificada em ordem crescente.
No entanto, se os thresholds forem configurados em uma ordem diferente, os valores serão classificados em ordem crescente após a atualização da configuração do widget no frontend do Zabbix (por exemplo, `"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|
|-|--------|--|--------|-------------------------------|
|*Cor de fundo*|<|1|bg_color|Código hexadecimal de cor (por exemplo, `FF0000`).
Padrão: `""` (vazio).|
|*Thresholds*|<|<|<|<|
|<|*Cor*|1|thresholds.0.color|Código hexadecimal de cor (por exemplo, `FF0000`).|
|^|*Threshold*|1|thresholds.0.threshold|Qualquer valor de string.|
|*Função de agregação*|<|0|aggregate_function|0 - *(padrão)* não usado;
1 - min;
2 - max;
3 - avg;
4 - count;
5 - sum;
6 - first;
7 - last.|
|*Período de tempo*|<|1|time_period.\_reference|`DASHBOARD._timeperiod` - define o [*seletor de período de tempo*](/manual/web_interface/time_period_selector) como a fonte de dados;
`ABCDE._timeperiod` - define um [widget compatível](/manual/web_interface/frontend_sections/dashboards/widgets#widget-compatibility) (com seu parâmetro `reference` igual a `ABCDE`) como a fonte de dados.
Padrão: `DASHBOARD._timeperiod`
Alternativamente, você pode definir o período de tempo apenas nos parâmetros *From* e *To*.
[Comportamento do parâmetro](/manual/api/reference_commentary#parameter-behavior):
- *suportado* se *Função de agregação* estiver definida como "min", "max", "avg", "count", "sum", "first", "last"|
|<|*From*|1|time_period.from|String de tempo válida em sintaxe absoluta (`YYYY-MM-DD hh:mm:ss`) ou [relativa](/manual/web_interface/time_period_selector) (`now`, `now/d`, `now/w-1w`, etc.).
[Comportamento do parâmetro](/manual/api/reference_commentary#parameter-behavior):
- *suportado* se *Período de tempo* não estiver definido e *Função de agregação* estiver definida como "min", "max", "avg", "count", "sum", "first", "last"
- *obrigatório* se `time_period.to` estiver definido|
|^|*To*|1|time_period.to|String de tempo válida em sintaxe absoluta (`YYYY-MM-DD hh:mm:ss`) ou [relativa](/manual/web_interface/time_period_selector) (`now`, `now/d`, `now/w-1w`, etc.).
[Comportamento do parâmetro](/manual/api/reference_commentary#parameter-behavior):
- *suportado* se *Período de tempo* não estiver definido e *Função de agregação* estiver definida como "min", "max", "avg", "count", "sum", "first", "last"
- *obrigatório* se `time_period.from` estiver definido|
|*Dados de histórico*|<|0|history|0 - *(padrão)* Auto;
1 - History;
2 - Trends.|
[comment]: # ({/c697bfd0-3cc5f221})
[comment]: # ({bcaa25cb-1925c46d})
##### Descrição
Os seguintes parâmetros de configuração avançada são suportados se *Mostrar* estiver definido como "Descrição".
|Parâmetro|[tipo](/manual/api/reference/dashboard/object#dashboard-widget-field)|nome|valor|
|-----|-|-----|-------------------|
|*Descrição*|1|description|Qualquer valor de string, incluindo macros.
Macros suportadas: {HOST.\*}, {ITEM.\*}, {INVENTORY.\*}, Macros de usuário.
Padrão: {ITEM.NAME}.|
|*Posição horizontal*|0|desc_h_pos|0 - Esquerda;
1 - *(padrão)* Centro;
2 - Direita.
Dois ou mais elementos (Descrição, Valor, Hora) não podem compartilhar a mesma *Posição horizontal* e *Posição vertical*.|
|*Posição vertical*|0|desc_v_pos|0 - Topo;
1 - Meio;
2 - *(padrão)* Inferior.
Dois ou mais elementos (Descrição, Valor, Hora) não podem compartilhar a mesma *Posição horizontal* e *Posição vertical*.|
|*Tamanho*|0|desc_size|Os valores possíveis variam de 1-100.
Padrão: 15.|
|*Negrito*|0|desc_bold|0 - *(padrão)* Desabilitado;
1 - Habilitado.|
|*Cor*|1|desc_color|Código de cor hexadecimal (ex.: `FF0000`).
Padrão: `""` (vazio).|
[comment]: # ({/bcaa25cb-1925c46d})
[comment]: # ({f2dff83b-9657b88c})
##### Valor
Os seguintes parâmetros de configuração avançada são suportados se *Mostrar* estiver definido como "Valor".
|Parâmetro|<|[tipo](/manual/api/reference/dashboard/object#dashboard-widget-field)|nome|valor|
|-|--------|--|--------|-------------------------------|
|*Casas decimais*|<|<|<|<|
|<|*Casas decimais*|0|decimal_places|Os valores possíveis variam de 1-10.
Padrão: 2.|
|^|*Tamanho*|0|decimal_size|Os valores possíveis variam de 1-100.
Padrão: 35.|
|*Posição*|<|<|<|<|
|<|*Posição horizontal*|0|value_h_pos|0 - Esquerda;
1 - *(padrão)* Centro;
2 - Direita.
Dois ou mais elementos (Descrição, Valor, Hora) não podem compartilhar a mesma *Posição horizontal* e *Posição vertical*.|
|^|*Posição vertical*|0|value_v_pos|0 - Superior;
1 - *(padrão)* Meio;
2 - Inferior.
Dois ou mais elementos (Descrição, Valor, Hora) não podem compartilhar a mesma *Posição horizontal* e *Posição vertical*.|
|^|*Tamanho*|0|value_size|Os valores possíveis variam de 1-100.
Padrão: 45.|
|^|*Negrito*|0|value_bold|0 - Desabilitado;
1 - *(padrão)* Habilitado.|
|^|*Cor*|1|value_color|Código de cor hexadecimal (por exemplo, `FF0000`).
Padrão: `""` (vazio).|
|*Unidades*|<|<|<|<|
|<|*Unidades* (checkbox)|0|units_show|0 - Desabilitado;
1 - *(padrão)* Habilitado.|
|^|*Unidades* (valor)|1|units|Qualquer valor de string.|
|^|*Posição*|0|units_pos|0 - Antes do valor;
1 - Acima do valor;
2 - *(padrão)* Após o valor;
3 - Abaixo do valor.|
|^|*Tamanho*|0|units_size|Os valores possíveis variam de 1-100.
Padrão: 35.|
|^|*Negrito*|0|units_bold|0 - Desabilitado;
1 - *(padrão)* Habilitado.|
|^|*Cor*|1|units_color|Código de cor hexadecimal (por exemplo, `FF0000`).
Padrão: `""` (vazio).|
[comment]: # ({/f2dff83b-9657b88c})
[comment]: # ({3e71dbcf-c0007d65})
##### Hora
Os seguintes parâmetros de configuração avançada são suportados se *Mostrar* estiver definido como "Hora".
|Parâmetro|[tipo](/manual/api/reference/dashboard/object#dashboard-widget-field)|nome|valor|
|-----|-|-----|-------------------|
|*Posição horizontal*|0|time_h_pos|0 - Esquerda;
1 - *(padrão)* Centro;
2 - Direita.
Dois ou mais elementos (Descrição, Valor, Hora) não podem compartilhar a mesma *Posição horizontal* e *Posição vertical*.|
|*Posição vertical*|0|time_v_pos|0 - *(padrão)* Superior;
1 - Meio;
2 - Inferior.
Dois ou mais elementos (Descrição, Valor, Hora) não podem compartilhar a mesma *Posição horizontal* e *Posição vertical*.|
|*Tamanho*|0|time_size|Os valores possíveis variam de 1-100.
Padrão: 15.|
|*Negrito*|0|time_bold|0 - *(padrão)* Desabilitado;
1 - Habilitado.|
|*Cor*|1|time_color|Código de cor hexadecimal (por exemplo, `FF0000`).
Padrão: `""` (vazio).|
[comment]: # ({/3e71dbcf-c0007d65})
[comment]: # ({2fbaf324-f824a1aa})
##### Indicador de alteração
Os seguintes parâmetros de configuração avançada são suportados se *Mostrar* estiver definido como "Indicador de alteração".
|Parâmetro|[tipo](/manual/api/reference/dashboard/object#dashboard-widget-field)|nome|valor|
|-----|-|-----|-------------------|
|*Cor do indicador de alteração ↑*|1|up_color|Código de cor hexadecimal (por exemplo, `FF0000`).
Padrão: `""` (vazio).|
|*Cor do indicador de alteração ↓*|1|down_color|Código de cor hexadecimal (por exemplo, `FF0000`).
Padrão: `""` (vazio).|
|*Cor do indicador de alteração ↕*|1|updown_color|Código de cor hexadecimal (por exemplo, `FF0000`).
Padrão: `""` (vazio).|
[comment]: # ({/2fbaf324-f824a1aa})
[comment]: # ({7f4e167c-7929c294})
##### Sparkline
Os seguintes parâmetros avançados de configuração são suportados se *Show* estiver definido como "Sparkline".
|Parameter|<|[type](/manual/api/reference/dashboard/object#dashboard-widget-field)|name|value|
|-|--------|--|--------|-------------------------------|
|*Width*|<|0|sparkline.width|Os valores possíveis variam de 0 a 10.
Padrão: 1.|
|*Fill*|<|0|sparkline.fill|Os valores possíveis variam de 0 a 10.
Padrão: 3.|
|*Color*|<|1|sparkline.color|Código hexadecimal de cor (por exemplo, `FF0000`).
Padrão: `42A5F5`.|
|*Time period*|<|1|sparkline.time_period.\_reference|`DASHBOARD._timeperiod` - define o [seletor de *Time period*](/manual/web_interface/time_period_selector) como a fonte de dados;
`ABCDE._timeperiod` - define um [widget compatível](/manual/web_interface/frontend_sections/dashboards/widgets#widget-compatibility) (com o parâmetro `reference` igual a `ABCDE`) como a fonte de dados.
Padrão: `DASHBOARD._timeperiod`
Como alternativa, você pode definir o período de tempo apenas nos parâmetros *From* e *To*.|
|<|*From*|1|sparkline.time_period.from|String de tempo válida em sintaxe absoluta (`YYYY-MM-DD hh:mm:ss`) ou [relativa](/manual/web_interface/time_period_selector) (`now`, `now/d`, `now/w-1w`, etc.).
[Comportamento do parâmetro](/manual/api/reference_commentary#parameter-behavior):
- *obrigatório* se `sparkline.time_period.to` estiver definido|
|^|*To*|1|sparkline.time_period.to|String de tempo válida em sintaxe absoluta (`YYYY-MM-DD hh:mm:ss`) ou [relativa](/manual/web_interface/time_period_selector) (`now`, `now/d`, `now/w-1w`, etc.).
[Comportamento do parâmetro](/manual/api/reference_commentary#parameter-behavior):
- *obrigatório* se `sparkline.time_period.from` estiver definido|
|*History data*|<|0|sparkline.history|0 - *(padrão)* Automático;
1 - Histórico;
2 - Tendências.|
[comment]: # ({/7f4e167c-7929c294})
[comment]: # ({fd9ac7eb-7c28c6ce})
### Exemplos
Os exemplos a seguir têm como objetivo apenas descrever a configuração dos objetos de campo do widget de dashboard para o widget *Valor do item*.
Para mais informações sobre a configuração de um dashboard, consulte [`dashboard.create`](/manual/api/reference/dashboard/create).
[comment]: # ({/fd9ac7eb-7c28c6ce})
[comment]: # ({61d2e13d-e1b71728})
#### Configurando um widget *Valor do item*
Configure um widget *Valor do item* que exibe o valor do item para o item "42266" (Disponibilidade do agent Zabbix).
Além disso, ajuste visualmente o widget com várias opções avançadas, incluindo uma cor de fundo dinâmica
que muda com base no status de disponibilidade do agent Zabbix.
[Requisição](/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
}
```
Resposta:
```json
{
"jsonrpc": "2.0",
"result": {
"dashboardids": [
"3"
]
},
"id": 1
}
```
[comment]: # ({/61d2e13d-e1b71728})
[comment]: # ({e9d30322-d0066a0f})
### Veja também
- [Campo de widget de dashboard](/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})