Table of Contents
Apêndice 1. Comentário de referência
Notação
Tipos de dados
A API do Zabbix suporta os seguintes tipos de dados como entrada:
| Tipo | Descrição |
|---|---|
| ID | Um identificador exclusivo usado para referenciar uma entidade. |
| boolean | Um valor booleano (true ou false). |
| flag | Um valor que é considerado true se passado e diferente de null; caso contrário, o valor é considerado false. |
| integer | Um número inteiro. |
| float | Um número de ponto flutuante. |
| string | Uma string de texto. |
| text | Uma string de texto mais longa. |
| timestamp | Um timestamp Unix. |
| array | Uma sequência ordenada de valores (um array simples). |
| object | Um array associativo. |
| query | Um valor que define os dados a serem retornados. O valor pode ser definido como um array de nomes de propriedades (para retornar apenas propriedades específicas), ou como um dos valores predefinidos:extend - retorna todas as propriedades do objeto;count - retorna o número de registros recuperados, suportado apenas por alguns subselects. |
A API do Zabbix sempre retorna valores apenas como strings ou arrays.
Comportamento da propriedade
Algumas das propriedades do objeto são marcadas com rótulos curtos para descrever seu comportamento. Os seguintes rótulos são usados:
- somente leitura - o valor da propriedade é definido automaticamente e não pode ser definido ou alterado pelo usuário, mesmo em algumas condições específicas (por exemplo, somente leitura para objetos herdados ou objetos descobertos);
- somente gravação - o valor da propriedade pode ser definido, mas não pode ser acessado posteriormente;
- constante - o valor da propriedade pode ser definido ao criar um objeto, mas não pode ser alterado posteriormente;
- suportado - o valor da propriedade não precisa ser definido, mas pode ser definido em algumas condições específicas (por exemplo, suportado se
typeestiver definido como "Verificação simples", "Verificação externa", "agent SSH", "agent TELNET" ou "agent HTTP"); observe, no entanto, que as propriedades suportadas ainda podem ser definidas para seus valores padrão, independentemente das condições; - obrigatório - o valor da propriedade deve ser definido para todas as operações (exceto operações get) ou em algumas condições específicas (por exemplo, obrigatório para operações de criação; obrigatório se
operationtypeestiver definido como "script global" eopcommand_hstnão estiver definido).
Para operações de atualização, uma propriedade é considerada como "definida" ao defini-la durante a operação de atualização.
As propriedades que não estão marcadas com rótulos são opcionais.
Comportamento dos parâmetros
Alguns dos parâmetros de operação são marcados com rótulos curtos para descrever seu comportamento para a operação. Os seguintes rótulos são usados:
- somente leitura - o valor do parâmetro é definido automaticamente e não pode ser definido ou alterado pelo usuário, mesmo em algumas condições específicas (por exemplo, somente leitura para objetos herdados ou objetos descobertos);
- somente gravação - o valor do parâmetro pode ser definido, mas não pode ser acessado depois;
- suportado - o valor do parâmetro não é obrigatório, mas pode ser definido em algumas condições específicas (por exemplo, suportado se
operating_modedo objeto proxy estiver definido como "proxy passivo"); observe, no entanto, que parâmetros suportados ainda podem ser definidos para seus valores padrão, independentemente das condições; - obrigatório - o valor do parâmetro é obrigatório.
Parâmetros que não são marcados com rótulos são opcionais.
Valor de ID reservado "0"
O valor de ID reservado "0" pode ser usado para filtrar elementos e para remover objetos referenciados. Por exemplo, para remover um proxy referenciado de um host, proxyid deve ser definido como 0 ("proxyid": "0") ou para filtrar hosts monitorados pela opção server, proxyids deve ser definido como 0 ("proxyids": "0").
Parâmetros comuns do método "get"
Os seguintes parâmetros são suportados por todos os métodos get:
| Parâmetro | Tipo | Descrição |
|---|---|---|
| countOutput | boolean | Retorna o número de registros no resultado em vez dos dados reais. |
| editable | boolean | Se definido como true, retorna apenas objetos para os quais o usuário tem permissões de gravação.Padrão: false. |
| excludeSearch | boolean | Retorna resultados que não correspondem aos critérios fornecidos no parâmetro search. |
| filter | object | Retorna apenas os resultados que correspondem exatamente ao filtro fornecido. Aceita um objeto, onde as chaves são nomes de propriedades (por exemplo, propriedades do objeto Host em host.get, propriedades do objeto Item em item.get, etc.), e os valores são um único valor ou um array de valores para comparar.Não suporta propriedades do tipo de dado text.Observe que alguns métodos têm funcionalidades específicas para este parâmetro, que são descritas na página do método (por exemplo, o parâmetro filter em host.get também suporta propriedades da interface do Host). |
| limit | integer | Limita o número de registros retornados. |
| output | query | Propriedades do objeto a serem retornadas. Padrão: extend. |
| preservekeys | boolean | Usa os IDs como chaves no array resultante. |
| search | object | Retorna resultados que correspondem ao padrão fornecido (não diferencia maiúsculas de minúsculas). Aceita um objeto, onde as chaves são nomes de propriedades (por exemplo, propriedades do objeto Host em host.get, propriedades do objeto Item em item.get, etc.), e os valores são strings a serem pesquisadas. Se nenhuma opção adicional for fornecida, será realizada uma pesquisa LIKE "%…%".Suporta apenas propriedades dos tipos de dado string e text.Observe que alguns métodos têm funcionalidades específicas para este parâmetro, que são descritas na página do método (por exemplo, o parâmetro search em host.get também suporta propriedades da interface do Host). |
| searchByAny | boolean | Se definido como true, retorna resultados que correspondem a qualquer um dos critérios fornecidos nos parâmetros filter ou search em vez de todos eles.Padrão: false. |
| searchWildcardsEnabled | boolean | Se definido como true, permite o uso de "*" como caractere curinga no parâmetro search.Padrão: false. |
| sortfield | string/array | Ordena o resultado pelas propriedades fornecidas. Consulte a descrição do método get da API específica para obter uma lista de propriedades que podem ser usadas para ordenação. As macros não são expandidas antes da ordenação. Se nenhum valor for especificado, os dados serão retornados sem ordenação. |
| sortorder | string/array | Ordem de classificação. Se um array for passado, cada valor será associado à propriedade correspondente fornecida no parâmetro sortfield.Valores possíveis: ASC - (padrão) crescente;DESC - decrescente. |
| startSearch | boolean | O parâmetro search irá comparar o início dos campos, ou seja, realizará uma pesquisa LIKE "…%".Ignorado se searchWildcardsEnabled estiver definido como true. |
Flags de origem da entidade
Os métodos Get retornam uma propriedade flags para entidades relacionadas à descoberta de baixo nível (regra LLD/protótipo de regra LLD, item/protótipo de item, etc). Esta propriedade é útil para indicar se a entidade foi descoberta ou não, já que a edição de entidades descobertas é limitada.
A propriedade flags retorna um resultado baseado em uma combinação (operação "+") destes valores:
| Valor | Descrição |
|---|---|
| 0 | Entidade base (item, trigger, gráfico, host) |
| 1 | Regra de descoberta de baixo nível |
| 2 | Qualquer protótipo (protótipo de item, protótipo de trigger, protótipo de regra LLD, etc) |
| 4 | Entidade descoberta (item, trigger, gráfico, host, regra LLD descobertos) |
O valor combinado retornado pela propriedade flags pode ser:
| Valor | Combinação de | Descrição |
|---|---|---|
| 0 | 0 | Entidade simples (item, trigger, gráfico, host). |
| 2 | 2 | Protótipo de entidade (protótipo de item, protótipo de trigger, etc). |
| 6 | 2+4 | Item, trigger, gráfico, host descobertos (convertidos de protótipo). |
| 1 | 1 | Regra de descoberta de baixo nível. |
| 3 | 1+2 | Protótipo de regra de descoberta de baixo nível. |
| 5 | 1+4 | Regra de descoberta de baixo nível descoberta (convertida de protótipo). |
| 7 | 1+2+4 | Protótipo de regra de descoberta de baixo nível descoberta. |
Exemplos
Verificação de permissão do usuário
O usuário tem permissão para gravar em hosts cujos nomes começam com "MySQL" ou "Linux"?
{
"jsonrpc": "2.0",
"method": "host.get",
"params": {
"countOutput": true,
"search": {
"host": ["MySQL", "Linux"]
},
"editable": true,
"startSearch": true,
"searchByAny": true
},
"id": 1
}Resposta:
Resultado zero significa que não há hosts com permissões de leitura/gravação.
Contagem de não correspondências
Conte o número de hosts cujos nomes não contêm a substring "ubuntu"
{
"jsonrpc": "2.0",
"method": "host.get",
"params": {
"countOutput": true,
"search": {
"host": "ubuntu"
},
"excludeSearch": true
},
"id": 1
}Resposta:
Pesquisando hosts usando curingas
Encontre hosts cujo nome contenha a palavra "server" e que tenham portas de interface "10050" ou "10071". Classifique o resultado pelo nome do host em ordem decrescente e limite a 5 hosts.
{
"jsonrpc": "2.0",
"method": "host.get",
"params": {
"output": ["hostid", "host"],
"selectInterfaces": ["port"],
"filter": {
"port": ["10050", "10071"]
},
"search": {
"host": "*server*"
},
"searchWildcardsEnabled": true,
"searchByAny": true,
"sortfield": "host",
"sortorder": "DESC",
"limit": 5
},
"id": 1
}Resposta:
{
"jsonrpc": "2.0",
"result": [
{
"hostid": "50003",
"host": "WebServer-Tomcat02",
"interfaces": [
{
"port": "10071"
}
]
},
{
"hostid": "50005",
"host": "WebServer-Tomcat01",
"interfaces": [
{
"port": "10071"
}
]
},
{
"hostid": "50004",
"host": "WebServer-Nginx",
"interfaces": [
{
"port": "10071"
}
]
},
{
"hostid": "99032",
"host": "MySQL server 01",
"interfaces": [
{
"port": "10050"
}
]
},
{
"hostid": "99061",
"host": "Linux server 01",
"interfaces": [
{
"port": "10050"
}
]
}
],
"id": 1
}Pesquisando hosts usando curingas com "preservekeys"
Se você adicionar o parâmetro "preservekeys" à solicitação anterior, o resultado será retornado como um array associativo, onde as chaves são o id dos objetos.
{
"jsonrpc": "2.0",
"method": "host.get",
"params": {
"output": ["hostid", "host"],
"selectInterfaces": ["port"],
"filter": {
"port": ["10050", "10071"]
},
"search": {
"host": "*server*"
},
"searchWildcardsEnabled": true,
"searchByAny": true,
"sortfield": "host",
"sortorder": "DESC",
"limit": 5,
"preservekeys": true
},
"id": 1
}Resposta:
{
"jsonrpc": "2.0",
"result": {
"50003": {
"hostid": "50003",
"host": "WebServer-Tomcat02",
"interfaces": [
{
"port": "10071"
}
]
},
"50005": {
"hostid": "50005",
"host": "WebServer-Tomcat01",
"interfaces": [
{
"port": "10071"
}
]
},
"50004": {
"hostid": "50004",
"host": "WebServer-Nginx",
"interfaces": [
{
"port": "10071"
}
]
},
"99032": {
"hostid": "99032",
"host": "MySQL server 01",
"interfaces": [
{
"port": "10050"
}
]
},
"99061": {
"hostid": "99061",
"host": "Linux server 01",
"interfaces": [
{
"port": "10050"
}
]
}
},
"id": 1
}