19 API

Visão Geral

A API do Zabbix permite que você recupere e modifique programaticamente a configuração do Zabbix e fornece acesso a dados históricos. Isto é amplamente utilizado para:

• Criar novos aplicativos para trabalhar com Zabbix;
• Integrar o Zabbix com softwares de terceiros;
• Automatizar tarefas de rotina.

A API do Zabbix é uma API baseada na web e é enviada como parte do frontend web. Ele 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 JSON format homepage.

Estrutura

A API consiste em vários métodos que são nominalmente agrupados em APIs separadas. Cada um dos métodos executa uma tarefa específica. Por exemplo, o método host.create pertence à API host e é usado para criar novos hosts. Historicamente, as APIs são às vezes referidas como "classes".

Realizando solicitações

Uma vez que você tenha configurado o frontend, pode usar solicitações HTTP remotas para chamar a API. Para fazer isso, você precisa enviar solicitações HTTP POST para o arquivo api_jsonrpc.php localizado no diretório do frontend. Por exemplo, se o seu frontend do Zabbix estiver instalado em https://example.com/zabbix, uma solicitação HTTP para chamar o método apiinfo.version pode se parecer com isto:frontend

curl --request POST \
           --url 'https://example.com/zabbix/api_jsonrpc.php' \
           --header 'Content-Type: application/json-rpc' \
           --data '{"jsonrpc":"2.0","method":"apiinfo.version","params":{},"id":1}'

A solicitação deve ter o cabeçalho Content-Type definido como um destes valores: application/json-rpc, application/json ou application/jsonrequest.

O objeto da solicitação contém as seguintes propriedades:

• 'jsonrpc' - a versão do protocolo JSON-RPC usado pela API (a API do Zabbix implementa a versão 2.0 do JSON-RPC);
• 'method' - o método da API que está sendo chamado;
• 'params' - os parâmetros que serão passados para o método da API;
• 'id' - um identificador arbitrário da solicitação.

Se a solicitação estiver correta, a resposta retornada pela API deve se parecer com isto:

{
            "jsonrpc": "2.0",
            "result": "6.4.0",
            "id": 1
       }

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

• 'jsonrpc' - a versão do protocolo JSON-RPC;
• 'result' - os dados retornados pelo método;
• 'id' - um identificador da solicitação correspondente.

Exemplo de fluxo de trabalho

A seção a seguir irá guiá-lo por alguns exemplos de uso em maior detalhe.

Autenticação

Antes de você acessar qualquer dado dentro do Zabbix 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 Zabbix. 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 Zabbix 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.

Authorization methods

By "Authorization" header

All API requests require an authentication or an API token. You can provide the credentials by using the "Authorization" request header:

curl --request POST \
         --url 'https://company.com/zabbix/ui/api_jsonrpc.php' \
         --header 'Authorization: Bearer 0424bd59b807674191e7d77572075f33'

By "auth" property

An API request can be authorized by the "auth" property.

curl --request POST \
         --url 'https://company.com/zabbix/ui/api_jsonrpc.php' \
         --header 'Content-Type: application/json-rpc' \
         --data '{"jsonrpc":"2.0","method":"host.get","params":{"output":["hostid"]},"auth":"0424bd59b807674191e7d77572075f33","id":1}'

By Zabbix cookie

A "zbx_session" cookie is used to authorize an API request from Zabbix UI performed using JavaScript (from a module or a custom widget).

Recuperando hosts

Agora podemos utilizar o token de autenticação para acessar dados no Zabbix. 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": "Zabbix server",
                   "interfaces": [
                       {
                           "interfaceid": "1",
                           "ip": "127.0.0.1"
                       }
                   ]
               }
           ],
           "id": 2
       }

Criando um novo item

Vamos criar um novo item no "Zabbix 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 Zabbix 2.0.4, a versão da API é igual a versão do Zabbix. 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 Zabbix, mas não pare aqui, temos uma extensiva documentação sobre os métodos disponíveis.

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 crie outro host chamando host.create, mas omitindo o parâmetro obrigatório groups.

{
           "jsonrpc": "2.0",
           "método": "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": {
               "código": -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 valores, um tempo limite de sessão ou tentar acessar objetos inexistentes. Seu o aplicativo deve ser capaz de lidar com esses tipos de erros.

Versões da API

Para simplificar o versionamento da API, desde o Zabbix 2.0.4, a versão da API corresponde à versão do próprio Zabbix. Você pode usar o apiinfo.version método 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. Ocasionalmente, podemos remover recursos entre os principais lançamentos sem fornecer nenhum compatibilidade. É importante que você nunca confie em nenhum recursos e migrar para alternativas mais recentes o mais rápido possível.

Leitura adicional

Agora você já sabe o suficiente para começar a trabalhar com a API do Zabbix, mas não pare aqui. Para leitura adicional, sugerimos que você dê uma olhada na lista de APIs disponíveis.