[comment]: # ({6d056871-6d056871}) # Apêndice 1. Comentário de referência [comment]: # ({/6d056871-6d056871}) [comment]: # ({6594bdc4-6594bdc4}) ### Notação [comment]: # ({/6594bdc4-6594bdc4}) [comment]: # ({8c926b1a-2df08058}) #### 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.| ::: noteimportant A API do Zabbix sempre retorna valores apenas como strings ou arrays. ::: [comment]: # ({/8c926b1a-2df08058}) [comment]: # ({8f68b338-a2c16a18}) #### 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 `type` estiver 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 `operationtype` estiver definido como "script global" e `opcommand_hst` não estiver definido). ::: noteclassic 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. [comment]: # ({/8f68b338-a2c16a18}) [comment]: # ({f960f4be-f255da9d}) #### 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_mode` do 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. [comment]: # ({/f960f4be-f255da9d}) [comment]: # ({cf59def4-5e99748d}) ### 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"). [comment]: # ({/cf59def4-5e99748d}) [comment]: # ({da9957c2-b4e0f5ab}) ### Parâmetros comuns do método "get" Os seguintes parâmetros são suportados por todos os métodos `get`: |Parâmetro|[Tipo](#data-types)|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 escrita.

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` [data type](#data-types).

Observe que alguns métodos possuem 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](/manual/api/reference/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.

Observe que o ID do objeto (ou seja, `hostid`, `itemid`, etc.) é sempre incluído na resposta, mesmo que não seja especificado no parâmetro `output`.

Padrão: `extend`.| |preservekeys|boolean|Usa os IDs como chaves no array resultante.| |search|object|Retorna resultados que correspondem ao padrão fornecido (case-insensitive).

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 busca `LIKE "%…%"`.

Suporta apenas propriedades dos tipos de dado `string` e `text` [data type](#data-types).

Observe que alguns métodos possuem 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](/manual/api/reference/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`, habilita 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 de um método get específico da API para obter uma lista de propriedades que podem ser usadas para ordenação. 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 ordenação. Se um array for passado, cada valor será associado à propriedade correspondente fornecida no parâmetro `sortfield`.

Valores possíveis:
`ASC` - *(padrão)* ascendente;
`DESC` - descendente.| |startSearch|boolean|O parâmetro `search` irá comparar o início dos campos, ou seja, realizará uma busca `LIKE "…%"`.

Ignorado se `searchWildcardsEnabled` estiver definido como `true`.| [comment]: # ({/da9957c2-b4e0f5ab}) [comment]: # ({1f52febe-4a0aeab6}) ### 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.| [comment]: # ({/1f52febe-4a0aeab6}) [comment]: # ({b41637d2-b41637d2}) ### Exemplos [comment]: # ({/b41637d2-b41637d2}) [comment]: # ({7f8a25ac-7a121fac}) #### 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"? [Requisição](/manual/api#performing-requests): ```json { "jsonrpc": "2.0", "method": "host.get", "params": { "countOutput": true, "search": { "host": ["MySQL", "Linux"] }, "editable": true, "startSearch": true, "searchByAny": true }, "id": 1 } ``` Resposta: ```json { "jsonrpc": "2.0", "result": "0", "id": 1 } ``` ::: noteclassic Resultado zero significa que não há hosts com permissões de leitura/gravação. ::: [comment]: # ({/7f8a25ac-7a121fac}) [comment]: # ({b814e950-ea3cccd8}) #### Contagem de não correspondências Conte o número de hosts cujos nomes não contêm a substring "ubuntu" [Requisição](/manual/api#performing-requests): ```json { "jsonrpc": "2.0", "method": "host.get", "params": { "countOutput": true, "search": { "host": "ubuntu" }, "excludeSearch": true }, "id": 1 } ``` Resposta: ```json { "jsonrpc": "2.0", "result": "44", "id": 1 } ``` [comment]: # ({/b814e950-ea3cccd8}) [comment]: # ({a325f949-e911c08b}) #### 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. [Requisição](/manual/api#performing-requests): ```json { "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: ```json { "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 } ``` [comment]: # ({/a325f949-e911c08b}) [comment]: # ({8c8fa5f6-8ce6f554}) #### 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. [Requisição](/manual/api#performing-requests): ```json { "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: ```json { "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 } ``` [comment]: # ({/8c8fa5f6-8ce6f554})