韓誥傭痔

Table of Contents

18. API

18. API

Vis?o Geral

A API do 韓誥傭痔 permite que voc那, de forma program芍tica, receba e modifica as configura??es do 韓誥傭痔, al谷m de prover acesso a dados hist車ricos e das m谷dias. Ela pode ser utilizada, por exemplo, para:

Criar novas aplica??es para trabalhar com o 韓誥傭痔;
Integrar o 韓誥傭痔 com softwares de terceiros;
Automatizar tarefas rotineiras.

A API 谷 um servi?o web fornecido em conjunto com a Interface Web do 韓誥傭痔. Esta API utiliza JSON, em sua vers?o 2, e duas formas de trabalho:

A API 谷 separada em dois conjuntos de m谷todos;
As requisi??es e respostas entre os clientes s?o codificadas no formato JSON.

Maiores informa??es sobre o protocolo JSON podem ser obtidas em e na .

Estrutura

A API consiste em uma quantidade de m谷todos que s?o nominalmente separados como APIs individuais. Cada um destes m谷todos executa uma tarefa espec赤fica. Por exemplo, o m谷todo host.create pertence 角 API host e 谷 utilizada para criar novos hosts. Historicamente as APIs s?o referidas como "classes".

A maioria das APIs possuem quatro m谷todos: get, create, update e delete para, respectivamente, recuperar, criar, atualizar e excluir dados, mas algumas das APIs podem possuir m谷todos totalmente diferentes.

Executando as requisi??es

Uma vez que voc那 tenha configurado a interface web do 韓誥傭痔 voc那 pode utilizar-se de requisi??es HTTP para invocar a API. Para fazer isso voc那 precisa enviar requisi??es no padr?o HTTP POST para o arquivo api_jsonrpc.php localizado na raiz da interface web. Por exemplo, se sua instala??o do 韓誥傭痔 est芍 no endere?o http://company.com/zabbix, a requisi??o HTTP para o m谷todo apiinfo.version pode ser algo como a seguir:

POST http://company.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 precisa possuir o cabe?alho com o Content-Type definido com um destes valores : application/json-rpc, application/json ou application/jsonrequest.

Voc那 pode utilizar qualquer cliente HTTP ou ferramenta de teste JSON-RPC para requisitar os m谷todos da API manualmente, mas n車s recomendamos o uso de uma das APIs .

Exemplo de fluxo de trabalho

Esta se??o ir芍 demonstrar com mais detalhes, atrav谷s de exemplos, como trabalhar com a API.

Autentica??o

Antes de voc那 acessar qualquer dado dentro do 韓誥傭痔 voc那 precisa se autenticar e obter um token de autentica??o. Isso pode ser feito utilizando o m谷todo user.login. Vamos supor que voc那 queira se autenticar como um usu芍rio comum do 韓誥傭痔. A requisi??o JSON a seguir poderia fazer isso:

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

Vamos olhar mais de perto o objeto de requisi??o. Ele tem as seguintes propriedades:

jsonrpc - a vers?o do protocolo JSON-RPC utilizado pela API; o 韓誥傭痔 implementa a API usando a vers?o 2;
method - o m谷todo a ser chamado na API;
params - os par?metros que ser?o passados para o m谷todo da API;
id - um identificador arbitr芍rio do pedido;
auth - um token de autentica??o de usu芍rio; uma vez que ainda n?o o temos, deve ser definido como null.

Se voc那 oferecer as credenciais corretamente ,a resposta retornada pela API ser芍 o token de autentica??o:

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

O objeto de resposta cont那m algumas propriedades:

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

Recuperando hosts

Agora podemos utilizar o token de autentica??o para acessar dados no 韓誥傭痔. Por exemplo, vamos utilizar o m谷todo host.get para recuperar os IDs, nomes e interfaces de todos os hosts que o usu芍rio tiver acesso:

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

Observe que a propriedade auth agora est芍 definida com o token de autentica??o que obtivemos atrav谷s do m谷todo user.login.

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

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

Por quest?es de performance, 谷 recomendado sempre solicitar somente as propriedades que voc那 est芍 interessado, n?o solicitar propriedades que voc那 n?o ir芍 utilizar nestes momento.

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 mas pr車ximas refer那ncias:

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

O m谷todo item.create tamb谷m pode ser utilizado m迆ltiplos itens em uma mesma chamada, atrav谷s de arrays de dados.

Gerenciamento de erros

At谷 este ponto tudo o que tentamos deve ter funcionado corretamente. Mas o que aconteceria se n車s tent芍ssemos uma chamada incorreta 角 API? Vamos tentar criar outra chamada ao m谷todo host.create, mas omitindo a propriedade obrigat車ria groups .

{
           "jsonrpc": "2.0",
           "method": "host.create",
           "params": {
               "host": "Linux server",
               "interfaces": [
                   {
                       "type": 1,
                       "main": 1,
                       "useip": 1,
                       "ip": "192.168.3.1",
                       "dns": "",
                       "port": "10050"
                   }
               ]
           },
           "id": 3,
           "auth": "0424bd59b807674191e7d77572075f33"
       }

A resposta desta requisi??o ir芍 conter uma mensagem de erro:

{
           "jsonrpc": "2.0",
           "error": {
               "code": -32602,
               "message": "Invalid params.",
               "data": "No groups for host \"Linux server\"."
           },
           "id": 3
       }

Se um erro ocorrer, ao inv谷s da propriedade result, a resposta ir芍 conter a propriedade error junto com os dados a seguir:

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

Erros podem ocorrer em diversas situa??es, tal qual, uso incorreto de valores, demora excessiva na sess?o ou tentar acessar objetos inexistentes. Sua aplica??o ter芍 que ter a habilidade de tratar corretamente destes erros.

vers?es da API

Para simplificar o versionamento da API, a partir do 韓誥傭痔 2.0.4, a vers?o da API 谷 igual a vers?o do 韓誥傭痔. Voc那 pode utilizar o m谷todo apiinfo.version para localizar a vers?o da API com a qual voc那 est芍 trabalhando. Este m谷todo em particular pode ser muito utilizado para ajustar a sua aplica??o para caracter赤sticas espec赤ficas de cada vers?o da API.

N車s garantimos compatibilidade retroativa. Quando ocorrem incompatibilidades entre a vers?o mais nova e a anterior, normalmente n車s deixamos a antiga funcionalidade como obsoleta na nova vers?o e a removemos ap車s algumas vers?es. Ocasionalmente, n車s podemos remover caracter赤sticas nas vers?es mais novas sem prover a retrocompatibilidade. Por isso 谷 importante que voc那 n?o mantenha o uso de funcionalidades marcadas como obsoletas, migrando os m谷todos para as suas alternativas sempre que poss赤vel.

Voc那 pode seguir todas as mudan?as feitas na API em log de altera??o API.

Outras leituras

Agora voc那 sabe o suficiente para come?ar a trabalhar com a API do 韓誥傭痔, mas n?o pare aqui, temos uma extensiva documenta??o sobre os m谷todos 餃勳莽梯棗紳赤措梗勳莽.