20 API

Visão geral

A API do Zabbix permite recuperar e modificar programaticamente a configuração do Zabbix e fornece acesso a dados históricos. Ela é amplamente utilizada para:

• criar novos aplicativos para trabalhar com o Zabbix;
• integrar o Zabbix a um software de terceiros;
• automatizar tarefas rotineiras.

A API do Zabbix é uma API baseada em HTTP e é fornecida como parte do frontend web. Ela utiliza o protocolo JSON-RPC 2.0, o que significa duas coisas:

• a API consiste em um conjunto de métodos separados;
• as solicitações e respostas entre os clientes e a API são codificadas usando o formato JSON.

Para mais informações sobre o protocolo e o JSON, consulte a especificação JSON-RPC 2.0 e a página inicial do formato JSON.

Para mais informações sobre como integrar a funcionalidade do Zabbix em seus aplicativos Python, consulte a biblioteca Python zabbix_utils para a API do Zabbix.

Estrutura

A API consiste em vários métodos que são agrupados nominalmente 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 vezes são chamadas de "classes".

Realizando solicitações

Depois de configurar o frontend, você pode usar solicitações HTTP remotas para chamar a API. Para isso, é necessário 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 ser assim:

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

O cabeçalho da solicitação deve ser definido como um destes valores: application/json-rpc, application/json ou application/jsonrequest.

O objeto da solicitação deve conter as seguintes propriedades:

• jsonrpc - a versão do protocolo JSON-RPC usada 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 omitido, a API trata a solicitação como uma notificação).

Se a solicitação estiver correta, a resposta retornada pela API deve ser semelhante a esta:

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

O objeto de 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

Para acessar qualquer dado no Zabbix, você precisa:

• usar um token de API existente (criado no frontend do Zabbix ou usando a API de Token);
• usar um token de autenticação obtido com o método user.login.

Por exemplo, se você quiser obter um novo token de autenticação fazendo login como o usuário padrão Admin, a solicitação JSON seria assim:

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

Se você forneceu as credenciais corretamente, a resposta retornada pela API deve conter o token de autenticação do usuário:

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

Métodos de autorização

Pelo cabeçalho "Authorization"

Todas as solicitações da API exigem autenticação ou um token de API. Você pode fornecer as credenciais usando o cabeçalho Authorization na solicitação:

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

A API do Zabbix aceita cabeçalhos de forma case-insensitive (por exemplo, authorization, Authorization e AUTHORIZATION são tratados da mesma forma).

O cabeçalho Authorization é suportado em solicitações de origem cruzada (CORS).

Por cookie do Zabbix

Um cookie "zbx_session" é usado para autorizar uma solicitação de API da interface do Zabbix realizada usando JavaScript (de um módulo ou de um widget personalizado).

Recuperando hosts

Agora você tem um token de autenticação de usuário válido que pode ser usado para acessar os dados no Zabbix. Por exemplo, você pode usar o método host.get para recuperar os IDs, nomes de host e interfaces de todos os hosts configurados:

Requisição:

curl --request POST \
         --url 'https://example.com/zabbix/api_jsonrpc.php' \
         --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \
         --header 'Content-Type: application/json-rpc' \
         --data @data.json

data.json

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

O objeto de resposta conterá os dados solicitados sobre os hosts:

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

Criando um novo item

Agora, crie um novo item no host "Zabbix server" usando os dados obtidos na solicitação anterior host.get. Isso pode ser feito usando o método item.create:

curl --request POST \
         --url 'https://example.com/zabbix/api_jsonrpc.php' \
         --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \
         --header 'Content-Type: application/json-rpc' \
         --data '{"jsonrpc":"2.0","method":"item.create","params":{"name":"Free disk space on /home/joe/","key_":"vfs.fs.size[/home/joe/,free]","hostid":"10084","type":0,"value_type":3,"interfaceid":"1","delay":30},"id":3}'

Uma resposta bem-sucedida conterá o ID do item recém-criado, que pode ser usado para referenciar o item nas próximas solicitações:

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

Criando múltiplos triggers

Assim, se os métodos de criação aceitarem arrays, você pode adicionar múltiplos triggers, por exemplo, este:

curl --request POST \
         --url 'https://example.com/zabbix/api_jsonrpc.php' \
         --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \
         --header 'Content-Type: application/json-rpc' \
         --data '{"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",}],"id":4}'

A resposta bem-sucedida conterá os IDs dos triggers recém-criados:

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

Atualizando um item

Habilite um item definindo seu status como "0":

curl --request POST \
         --url 'https://example.com/zabbix/api_jsonrpc.php' \
         --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \
         --header 'Content-Type: application/json-rpc' \
         --data '{"jsonrpc":"2.0","method":"item.update","params":{"itemid":"10092","status":0},"id":5}'

A resposta bem-sucedida conterá o ID do item atualizado:

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

Atualizando múltiplos triggers

Habilite múltiplos triggers definindo seu status como "0":

curl --request POST \
         --url 'https://example.com/zabbix/api_jsonrpc.php' \
         --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \
         --header 'Content-Type: application/json-rpc' \
         --data '{"jsonrpc":"2.0","method":"trigger.update","params":[{"triggerid":"13938","status":0},{"triggerid":"13939","status":0}],"id":6}'

A resposta bem-sucedida conterá os IDs dos triggers atualizados:

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

Tratamento de erros

Até o momento, tudo o que você tentou funcionou bem. Mas o que aconteceria se você tentasse fazer uma chamada incorreta para a API? Tente criar outro host chamando host.create, mas omitindo o parâmetro obrigatório groups:

curl --request POST \
         --url 'https://example.com/zabbix/api_jsonrpc.php' \
         --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \
         --header 'Content-Type: application/json-rpc' \
         --data '{"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}'

A resposta então conterá uma mensagem de erro:

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

Se ocorrer um erro, em vez da propriedade result, o objeto de resposta conterá a propriedade error com os seguintes dados:

• code - um código de erro;
• message - um resumo curto do erro;
• data - uma mensagem de erro mais detalhada.

Erros podem ocorrer em vários casos, como, uso de valores de entrada incorretos, expiração de sessão ou tentativa de acessar objetos inexistentes. Sua aplicação deve ser capaz de lidar graciosamente 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 método apiinfo.version para descobrir a versão da API com a qual está trabalhando. Isso pode ser útil para ajustar seu aplicativo para usar recursos específicos da versão.

O Zabbix garante compatibilidade de recursos com versões anteriores dentro de uma versão principal. Ao fazer alterações incompatíveis com versões anteriores entre versões principais, o Zabbix geralmente deixa os recursos antigos como obsoletos na próxima versão e só os remove na versão seguinte. Ocasionalmente, o Zabbix pode remover recursos entre versões principais sem fornecer nenhuma compatibilidade com versões anteriores. É importante que você nunca dependa de recursos obsoletos e migre para alternativas mais recentes o mais rápido possível.

Leitura adicional

Agora, você tem conhecimento suficiente para começar a trabalhar com a API do Zabbix, no entanto, não pare por aqui. Para leitura adicional, recomenda-se dar uma olhada na lista de APIs disponíveis.