Esta é uma tradução da página de documentação original em inglês. Ajude-nos a torná-la melhor.

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 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 Zabbix 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 Zabbix 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 mantidas pela comunidade.

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

Note that the "auth" property is deprecated. It will be removed in the future releases.

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

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

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

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

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

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 Zabbix, mas não pare aqui. Para leitura adicional, sugerimos que você dê uma olhada na lista de APIs disponíveis.