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

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

Estrutura

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

Desenvolvendo requisições

Uma vez que você tenha configurado o frontend, você pode usar requisições de HTTP remoto para requisitar a execução da API. Para isso, você precisará enviar requisições HTTP POST para o arquivo api_jsonrpc.php localizado no diretório frontend. Por exemplo, se sua instalação do frontend Zabbix está em http://example.com/zabbix, a requisição HTTP para o método pode ser algo como a seguir:

POST http://example.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 deve ter o header Content-Type configurado para um desses valores: application/json-rpc, application/json ou application/jsonrequest.

Exemplo de workflow

A seção seguinte irá guiá-lo com alguns exemplos de usos mais detalhados.

Autenticação

Para acessar qualquer dado no Zabbix, você precisa:

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

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

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

Vamos dar uma olhada mais de perto ao objeto solicitado. Ele tem as seguintes propriedades:

• jsonrpc - versão do protocolo JSON-RPC usada pela API; a API do Zabbix implementa a versão 2.0 de JSON-RPC;
• method - como método da API é chamado;
• params - os parâmetros serão passados para o método da API;
• id - um identificador arbitrário da solicitação;
• auth - um token de autenticação do usuário; enquanto não temos um, ele é definido como null.

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

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

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

• jsonrpc -novamente, a versão do protocolo do JSON-RPC;
• result - o dado retornado pelo método;
• id - identificador da solicitação correspondente.

Recuperando hosts

Agora nós temos um token de autenticação válido que pode ser utilizado para acessar para acessar os dados no Zabbix. We now have a valid user authentication token that can be used to access the data in Zabbix. Por exemplos, vamos usar o método host.get para recuperar as IDs, nomes e interfaces de todos os hosts configurados: hosts:

{
           "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 requisitado 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

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 para referenciar o item nas requisições a seguir:

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

Criando vários triggers

Se criar métodos aceita arrays, então podemos adicionar vários triggers triggers assim:

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

Uma resposta bem sucedida irá conter os IDs dos triggers criados recentemente:

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

Atualizando um item

Habilite um item, isto é, configure seu status para "0":

{
           "jsonrpc": "2.0",
           "method": "item.update",
           "params": {
               "itemid": "10092",
               "status": 0
           },
           "auth": "0424bd59b807674191e7d77572075f33",
           "id": 5
       }

Uma resposta bem sucedida irá conter uma ID do item atualizado:

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

Atualizando vários triggers

Habilite vários triggers, isto é, configure seu status para "0":

{
           "jsonrpc": "2.0",
           "method": "trigger.update",
           "params": [
               {
                   "triggerid": "13938",
                   "status": 0
               },
               {
                   "triggerid": "13939",
                   "status": 0
               }
           ],
           "auth": "0424bd59b807674191e7d77572075f33",
           "id": 6
       }

Uma resposta bem sucedida irá conter os IDs de triggers atualizados:

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

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 criar 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 de valores, um tempo limite de sessão ou tentar acessar objetos inexistentes. Seu 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 método apiinfo.version 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. As vezes , podemos remover recursos entre os principais lançamentos sem fornecer nenhuma compatibilidade. É importante que você nunca confie em nenhum recurso e migre 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.