韓誥傭痔

Table of Contents

19 API

19 API

Vis?o Geral

A API do 韓誥傭痔 permite que voc那 recupere e modifique programaticamente a configura??o do 韓誥傭痔 e fornece acesso a dados hist車ricos. Isto 谷 amplamente utilizado para:

Criar novos aplicativos para trabalhar com 韓誥傭痔;
Integrar o 韓誥傭痔 com softwares de terceiros;
Automatizar tarefas de rotina.

A API do 韓誥傭痔谷 uma API baseada na web e 谷 enviada como parte do frontend web. Ela usa o protocolo JSON-RPC 2.0, o que significam 2 coisas:

A API consiste em um conjunto de m谷todos separados;
Solicita??es e respostas entre os clientes e a API s?o codificadas usando o formato JSON.

Mais informa??es sobre o protocolo e JSON podem ser encontradas no [JSON-RPC 2.0 specification(http://www.jsonrpc.org/specification) e .

Para mais informa??es sobre como integrar a funcionalidade de Zabbin em seus aplicativos Python, consulte a biblioteca para API do 韓誥傭痔.

Estrutura

A API consiste em v芍rios m谷todos que s?o nominalmente agrupados em APIs separadas. Cada um dos m谷todos desempenha uma tarefa espec赤fica. Por exemplo, o m谷todo host.create pertence ao API host e 谷 usado para criar novos hosts. Historicamente, as APIs as vezes s?o chamadas de "classes".

A maioria das APIs cont谷m ao menos quatro m谷todos: get, create, update e delete para recuperar, criar, atualizar e excluir dados , respectivamente. Contudo, algumas APIs podem oferecer um conjunto de m谷todos totalmente diferente.

Desenvolvendo requisi??es

Uma vez que voc那 tenha configurado o frontend, voc那 pode usar requisi??es de HTTP remoto para requisitar a execu??o da API. Para isso, voc那 precisar芍 enviar requisi??es HTTP POST para o arquivo api_jsonrpc.php localizado no diret車rio frontend. Por exemplo, se sua instala??o do frontend 韓誥傭痔 est芍 em http://example.com/zabbix, a requisi??o HTTP para o m谷todo pode ser algo como a seguir:

POST http://example.com/zabbix/api_jsonrpc.php HTTP/1.1
       Content-Type: application/json-rpc
       
       {
           "jsonrpc": "2.0",
           "method": "apiinfo.version",
           "id": 1,
           "auth": null,
           "params": {}
       }

A requisi??o deve ter o header Content-Type configurado para um desses valores: application/json-rpc, application/json ou application/jsonrequest.

Exemplo de workflow

A se??o seguinte ir芍 gui芍-lo com alguns exemplos de usos mais detalhados.

Autentica??o

Para acessar qualquer dado no 韓誥傭痔, voc那 precisa:

usar uma API existente API token (criada no frontend 韓誥傭痔 ou usar a API Token API);
usar um token de autentica??o obtido com o m谷todo user.login.

Por exemplo, se voc那 quisesse obter um novo token de autentica??o ao fazer login como usu芍rio Admin padr?o, a solicita??o JSON seria assim:

{
           "jsonrpc": "2.0",
           "method": "user.login",
           "params": {
               "username": "Admin",
               "password": "zabbix"
           },
           "id": 1,
           "auth": null
       }

Vamos dar uma olhada mais de perto ao objeto solicitado. Ele tem as seguintes propriedades:

jsonrpc - vers?o do protocolo JSON-RPC usada pela API; a API do 韓誥傭痔 implementa a vers?o 2.0 de JSON-RPC;
method - como m谷todo da API 谷 chamado;
params - os par?metros ser?o passados para o m谷todo da API;
id - um identificador arbitr芍rio da solicita??o;
auth - um token de autentica??o do usu芍rio; enquanto n?o temos um, ele 谷 definido como null.

Se voc那 forneceu as credenciais corretamente, a resposta a ser retornada pela API ir芍 conter um token de autentica??o do usu芍rio:

{
           "jsonrpc": "2.0",
           "result": "0424bd59b807674191e7d77572075f33",
           "id": 1
       }

O objeto da resposta, por sua vez, cont谷m as seguintes propriedades:

jsonrpc -novamente, a vers?o do protocolo do JSON-RPC;
result - o dado retornado pelo m谷todo;
id - identificador da solicita??o correspondente.

Recuperando hosts

Agora n車s temos um token de autentica??o v芍lido que pode ser utilizado para acessar para acessar os dados no 韓誥傭痔. We now have a valid user authentication token that can be used to access the data in 韓誥傭痔. Por exemplos, vamos usar o m谷todo host.get para recuperar as IDs, nomes e interfaces de todos os hosts configurados: hosts:

{
           "jsonrpc": "2.0",
           "method": "host.get",
           "params": {
               "output": [
                   "hostid",
                   "host"
               ],
               "selectInterfaces": [
                   "interfaceid",
                   "ip"
               ]
           },
           "id": 2,
           "auth": "0424bd59b807674191e7d77572075f33"
       }

Observe que a propriedade auth agora est芍 configurada com o token de autentica??o que obtivemos atrav谷s douser.login.

O objeto de resposta ir芍 conter o dado requisitado sobre os hosts:

{
           "jsonrpc": "2.0",
           "result": [
               {
                   "hostid": "10084",
                   "host": "韓誥傭痔 server",
                   "interfaces": [
                       {
                           "interfaceid": "1",
                           "ip": "127.0.0.1"
                       }
                   ]
               }
           ],
           "id": 2
       }

Por quest?es de performance, 谷 sempre recomend芍vel listar as propriedades do objeto que voc那 deseja recuperar para evitar recuperar tudo.

Criando um novo item

Vamos criar um novo item no "韓誥傭痔 server" usando os dados que obtivemos atrav谷s do m谷todo anterior ( host.get). Isso pode ser feito atrav谷s do m谷todo item.create:

{
           "jsonrpc": "2.0",
           "method": "item.create",
           "params": {
               "name": "Free disk space on $1",
               "key_": "vfs.fs.size[/home/joe/,free]",
               "hostid": "10084",
               "type": 0,
               "value_type": 3,
               "interfaceid": "1",
               "delay": 30
           },
           "auth": "0424bd59b807674191e7d77572075f33",
           "id": 3
       }

Uma resposta bem sucedida ir芍 conter o ID do novo item criado, que poder芍 ser utilizado para referenciar o item nas requisi??es a seguir:

{
           "jsonrpc": "2.0",
           "result": {
               "itemids": [
                   "24759"
               ]
           },
           "id": 3
       }

O m谷todo item.create , assim como outros m谷todos criados, tamb谷m aceita arrays de objetos e cria pode criar v v芍rios itens com apenas uma APIcall.

Criando v芍rios triggers

Se criar m谷todos aceita arrays, ent?o podemos adicionar v芍rios triggers triggers assim:

{
           "jsonrpc": "2.0",
           "method": "trigger.create",
           "params": [
               {
                   "description": "Processor load is too high on {HOST.NAME}",
                   "expression": "last(/Linux server/system.cpu.load[percpu,avg1])>5",
               },
               {
                   "description": "Too many processes on {HOST.NAME}",
                   "expression": "avg(/Linux server/proc.num[],5m)>300",
               }
           ],
           "auth": "0424bd59b807674191e7d77572075f33",
           "id": 4
       }

Uma resposta bem sucedida ir芍 conter os IDs dos triggers criados recentemente:

{
           "jsonrpc": "2.0",
           "result": {
               "triggerids": [
                   "17369",
                   "17370"
               ]
           },
           "id": 4
       }

Atualizando um item

Habilite um item, isto 谷, configure seu status para "0":

{
           "jsonrpc": "2.0",
           "method": "item.update",
           "params": {
               "itemid": "10092",
               "status": 0
           },
           "auth": "0424bd59b807674191e7d77572075f33",
           "id": 5
       }

Uma resposta bem sucedida ir芍 conter uma ID do item atualizado:

{
           "jsonrpc": "2.0",
           "result": {
               "itemids": [
                   "10092"
               ]
           },
           "id": 5
       }

O m谷todo item.update, assim como outros m谷todos atualizados, tamb谷m aceita objetos de array e consegue atualizar v芍rios itens com apenas um acionamento da API.

Atualizando v芍rios triggers

Habilite v芍rios triggers, isto 谷, configure seu status para "0":

{
           "jsonrpc": "2.0",
           "method": "trigger.update",
           "params": [
               {
                   "triggerid": "13938",
                   "status": 0
               },
               {
                   "triggerid": "13939",
                   "status": 0
               }
           ],
           "auth": "0424bd59b807674191e7d77572075f33",
           "id": 6
       }

Uma resposta bem sucedida ir芍 conter os IDs de triggers atualizados:

{
           "jsonrpc": "2.0",
           "result": {
               "triggerids": [
                   "13938",
                   "13939"
               ]
           },
           "id": 6
       }

Este 谷 o m谷todo preferido de atualiza??o. Alguns m谷todos API como host.massupdate permitem escrever c車digos mais simples. Contudo, n?o 谷 recomend芍vel utilizar esses m谷todos, uma vez que eles ser?o removidos em vers?es futuras do 韓誥傭痔.

Manipula??o de erros

At谷 esse ponto, tudo o que tentamos funcionou bem. Mas, o que acontece se tentarmos fazer uma chamada incorreta para a API? Vamos tentar criar outro host chamando host.create, mas omitindo o par?metro obrigat車rio groups.

{
           "jsonrpc": "2.0",
           &梁喝棗喧;鳥谷喧棗餃棗&梁喝棗喧;: "host.create",
           "par?metros": {
               "host": "Servidor Linux",
               "interfaces": [
                   {
                       "tipo 1,
                       "principal": 1,
                       "useip": 1,
                       "ip": "192.168.3.1",
                       "dns": "",
                       "porta": "10050"
                   }
               ]
           },
           "id": 7,
           "auth": "0424bd59b807674191e7d77572075f33"
       }

A resposta conter芍 uma mensagem de erro:

{
           "jsonrpc": "2.0",
           "erro": {
               &梁喝棗喧;釵車餃勳眶棗&梁喝棗喧;: -32602,
               "message": "Par?metros inv芍lidos.",
               "data": "Nenhum grupo para host \"Servidor Linux\"."
           },
           "id": 7
       }

Se ocorreu um erro, em vez da propriedade result, a resposta object conter芍 uma propriedade error com os seguintes dados:

code - um c車digo de erro;
message - um breve resumo do erro;
data - uma mensagem de erro mais detalhada.

Erros podem ocorrer em diferentes casos, como, por exemplo, usar entrada incorreta de valores, um tempo limite de sess?o ou tentar acessar objetos inexistentes. Seu aplicativo deve ser capaz de lidar com esses tipos de erros.

Vers?es da API

Para simplificar o versionamento da API, desde o 韓誥傭痔 2.0.4, a vers?o da API corresponde 角 vers?o do pr車prio 韓誥傭痔. Voc那 pode usar o m谷todo apiinfo.version para encontrar a vers?o da API com a qual voc那 est芍 trabalhando. Isso pode ser 迆til para ajustar seu aplicativo para usar recursos espec赤ficos da vers?o.

Garantimos a compatibilidade com vers?es anteriores dentro de uma vers?o principal. Ao fazer altera??es incompat赤veis com vers?es anteriores entre vers?es principais, geralmente deixam os recursos antigos como obsoletos na pr車xima vers?o, e apenas remov那-los no lan?amento depois disso. As vezes , podemos remover recursos entre os principais lan?amentos sem fornecer nenhuma compatibilidade. ? importante que voc那 nunca confie em nenhum recurso e migre para alternativas mais recentes o mais r芍pido poss赤vel.

Voc那 pode acompanhar todas as altera??es feitas na API no registro de altera??es da API.

Leitura adicional

Agora voc那 j芍 sabe o suficiente para come?ar a trabalhar com a API do 韓誥傭痔, mas n?o pare aqui. Para leitura adicional, sugerimos que voc那 d那 uma olhada na lista de APIs dispon赤veis.