A API do Zabbix permite que você, de forma programática, receba e modifica as configurações do Zabbix, além de prover acesso a dados históricos e das médias. Ela pode ser utilizada, por exemplo, para:
A API é um serviço web fornecido em conjunto com a Interface Web do Zabbix. Esta API utiliza JSON, em sua versão 2, e duas formas de trabalho:
Maiores informações sobre o protocolo JSON podem ser obtidas em JSON-RPC 2.0 specification e na página do formato JSON.
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”.
get
, create
, update
e delete
para, respectivamente, recuperar, criar, atualizar e excluir dados, mas algumas das APIs podem possuir métodos totalmente diferentes.
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
.
Esta seção irá demonstrar com mais detalhes, através de exemplos, como trabalhar com a API.
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.
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" }
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 }
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 }
item.create
também pode ser utilizado múltiplos itens em uma mesma chamada, através de arrays de dados.
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.
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.
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.