Áú»¢¶Ä²©

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".

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.

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"
       }

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
       }

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
       }

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.

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 »å¾±²õ±è´Ç²Ô¨ª±¹±ð¾±²õ.

Error handling

Up to that point everything we've tried has worked fine. But what happens if we try to make an incorrect call to the API? Let's try to create another host by calling host.create but omitting the mandatory groups parameter.

{
           "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": 7,
           "auth": "0424bd59b807674191e7d77572075f33"
       }

The response will then contain an error message:

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

If an error occurred, instead of the result property, the response object will contain an error property with the following data:

• code - an error code;
• message - a short error summary;
• data - a more detailed error message.

Errors can occur in different cases, such as, using incorrect input values, a session timeout or trying to access unexisting objects. Your application should be able to gracefully handle these kinds of errors.

API versions

To simplify API versioning, since Áú»¢¶Ä²© 2.0.4, the version of the API matches the version of Áú»¢¶Ä²© itself. You can use the apiinfo.version method to find out the version of the API you're working with. This can be useful for adjusting your application to use version-specific features.

We guarantee feature backward compatibility inside of a major version. When making backward incompatible changes between major releases, we usually leave the old features as deprecated in the next release, and only remove them in the release after that. Occasionally, we may remove features between major releases without providing any backward compatibility. It is important that you never rely on any deprecated features and migrate to newer alternatives as soon as possible.

Further reading

You now know enough to start working with the Áú»¢¶Ä²© API, but don't stop here. For further reading we suggest you have a look at the list of available APIs.