API e automação

API é parte do frontend do Zabbix

O Zabbix 7.4 expõe uma API HTTP baseada em JSON-RPC 2.0. As chamadas são enviadas por HTTP POST ao arquivo api_jsonrpc.php do frontend.

Entenda o envelope antes dos métodos

{
  "jsonrpc": "2.0",
  "method": "host.get",
  "params": {
    "output": ["hostid", "host", "name"]
  },
  "id": 1
}

API token ou token obtido por user.login

No Zabbix 7.4, você pode usar um API token existente ou autenticar com user.login. Para chamadas autorizadas, o token pode ser enviado no cabeçalho HTTP Authorization: Bearer ....

curl --request POST \
  --url 'https://zabbix.exemplo/zabbix/api_jsonrpc.php' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Content-Type: application/json-rpc' \
  --data '{
    "jsonrpc":"2.0",
    "method":"host.get",
    "params":{"output":["hostid","host"]},
    "id":1
  }'

Token não concede mais privilégio que a identidade associada

O acesso depende do tipo de usuário, role e grupos/permissões. Métodos também podem ser bloqueados pela role. Algumas operações exigem nível administrativo; por exemplo, host.create é destinado a Admin/Super admin, sujeito às permissões da role.

Teste conectividade antes da automação

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

Esse teste separa problemas de URL/TLS/proxy reverso de problemas de autorização e lógica do script.

Peça somente os campos necessários

Métodos *.get possuem filtros e opções de seleção. Em ambientes grandes, retornar objetos completos sem necessidade aumenta payload, memória e tempo.

{
  "jsonrpc":"2.0",
  "method":"host.get",
  "params":{
    "output":["hostid","host","name"],
    "selectInterfaces":["interfaceid","ip","dns","port"],
    "filter":{"status":0}
  },
  "id":2
}

Consultar antes de criar

host.get recupera hosts e suporta filtros por grupos, IDs, interfaces, templates, tags e outros critérios. host.create cria hosts e exige associação a grupo; também pode receber interfaces, tags, templates, macros e inventário.

{
  "jsonrpc":"2.0",
  "method":"host.create",
  "params":{
    "host":"RTR-POP-01",
    "name":"Router POP 01",
    "groups":[{"groupid":"12"}],
    "interfaces":[{
      "type":2,
      "main":1,
      "useip":1,
      "ip":"192.0.2.10",
      "dns":"",
      "port":"161",
      "details":{"version":2,"community":"{$SNMP_COMMUNITY}","bulk":1}
    }],
    "tags":[
      {"tag":"site","value":"pop-01"},
      {"tag":"role","value":"router"}
    ]
  },
  "id":10
}

Interface é objeto de configuração, não só IP

Agent, SNMP, JMX e IPMI possuem tipos e propriedades distintas. Uma automação de rede deve validar endereço, porta, método de conexão e, no SNMP, versão e credenciais/macros antes de criar o host.

Automação deve vincular intenção, não coleções aleatórias

Descubra templates por nome/ID, valide compatibilidade e mantenha uma matriz vendor/model/role → template. Evite vincular template apenas porque o nome “parece certo”.

vendor=datacom
model=dm4610
role=access-switch
monitoring_profile=snmp-access-v1

Essa camada de mapeamento pode viver no seu inventário/CMDB ou em arquivo versionado.

Contexto deve nascer junto com o host

site=centro
region=rj
carrier=operadora-a
role=uplink
service=internet
environment=production

Macros permitem parametrizar templates sem clonagem. Segredos devem ser tratados como segredo e não como texto comum em repositório de código.

Defina a fonte de verdade

Se NetBox, GLPI, ERP, planilha controlada ou sistema interno é a fonte de verdade, o Zabbix deve receber o estado desejado. Não deixe operadores corrigirem manualmente a mesma informação em três sistemas sem reconciliação.

Pipeline recomendado para cadastrar equipamentos

1. Receber ativo da fonte de verdade.
2. Validar campos obrigatórios e endereço.
3. Normalizar vendor, modelo, site e função.
4. Consultar se o host já existe.
5. Resolver IDs de grupo, template e proxy.
6. Criar ou atualizar somente diferenças.
7. Aplicar tags/macros/inventário.
8. Validar que itens começaram a receber dados.
9. Registrar resultado e correlation ID.

Executar duas vezes deve produzir o mesmo estado

O padrão seguro é GET → comparar → CREATE/UPDATE se necessário → validar. Um script que sempre executa host.create não é um reconciliador.

desired = origem()
current = zabbix.host_get(desired.host)

if current is None:
    create(desired)
elif diff(current, desired):
    update(current.id, desired)
else:
    no_change()

Cliente mínimo com requests

import os
import requests

URL = "https://zabbix.exemplo/zabbix/api_jsonrpc.php"
TOKEN = os.environ["ZABBIX_TOKEN"]

def call(method, params):
    payload = {
        "jsonrpc": "2.0",
        "method": method,
        "params": params,
        "id": 1,
    }

    response = requests.post(
        URL,
        json=payload,
        headers={"Authorization": f"Bearer {TOKEN}"},
        timeout=15,
    )
    response.raise_for_status()
    body = response.json()

    if "error" in body:
        raise RuntimeError(body["error"])

    return body["result"]

hosts = call("host.get", {
    "output": ["hostid", "host", "name"]
})

for host in hosts:
    print(host)

Em produção, acrescente logging estruturado, retry seletivo, timeout, validação de schema, métricas e tratamento de segredo.

Configuração versionável e importação controlada

configuration.import aceita configuração serializada em YAML, XML ou JSON e regras para criação/atualização/remoção conforme o tipo de objeto.

A API não serve apenas para configuração

A referência 7.4 inclui APIs para history, trends, events, problems, SLA, services, audit log e outros objetos. Isso permite relatórios, integração com portais e enriquecimento operacional.

HTTP 200 não significa que a operação deu certo

Em JSON-RPC, erros da API aparecem no objeto error, normalmente com code, message e data. O cliente deve validar tanto HTTP quanto o corpo JSON.

{
  "jsonrpc":"2.0",
  "error":{
    "code":-32602,
    "message":"Invalid params.",
    "data":"..."
  },
  "id":7
}

Classifique erros em autenticação/autorização, validação, objeto inexistente, conflito de estado e falha transitória. Não faça retry cego de erro de parâmetro.

Automação amplia o blast radius

• HTTPS obrigatório em produção;
• token em secret manager/variável protegida;
• conta dedicada por integração;
• menor privilégio;
• expiração/rotação de tokens;
• restrição de origem por firewall/reverse proxy quando aplicável;
• nunca logar Authorization header;
• separar credenciais de leitura e escrita;
• dry-run para mudanças amplas.

Você precisa responder quem, quando, o quê e por quê

{
  "timestamp":"2026-08-26T14:00:00-03:00",
  "job":"zabbix-reconcile",
  "object":"RTR-POP-01",
  "operation":"host.update",
  "changed":["tags","templates"],
  "ticket":"CHG-1234",
  "result":"success"
}

Não dependa somente do log local do script. Combine logs da automação, Audit log do Zabbix e, quando existir, ticket/change.

Templates e políticas podem seguir pipeline

Um pipeline maduro não publica diretamente em produção após qualquer commit. Separe desenvolvimento, validação e promoção.

Automatizar 10 hosts e 10.000 hosts são problemas diferentes

• reduza payload com output seletivo;
• evite chamadas N+1 quando uma consulta agregada resolve;
• cacheie IDs estáveis durante a execução;
• processe em lotes controlados;
• meça latência e taxa de erros;
• defina timeout e retry com backoff para falhas transitórias;
• não paralelize escrita sem conhecer dependências e capacidade.

Diagnostique por camada

1. Teste DNS e HTTPS do frontend.
2. Teste apiinfo.version.
3. Valide URL exata de api_jsonrpc.php.
4. Valide Content-Type e JSON.
5. Valide token e expiração.
6. Valide role e permissões do objeto.
7. Leia error.code, message e data.
8. Reduza a chamada ao menor payload reproduzível.
9. Compare a operação com a referência 7.4 do método.
10. Verifique logs de frontend/web server e Audit log quando necessário.

Do GET seguro ao reconciliador

Antes de liberar uma automação

• versão alvo do Zabbix está declarada?
• métodos foram conferidos na referência 7.4?
• token possui menor privilégio?
• segredo está fora do código?
• HTTPS está validado?
• há timeout e tratamento de erro JSON-RPC?
• processo é idempotente?
• há dry-run para mudança em massa?
• há logs e correlation ID?
• há limite de escopo?
• há rollback?
• foi testado em laboratório?

Escopo factual

Os exemplos foram estruturados para Zabbix 7.4. A API oficial é HTTP/JSON-RPC 2.0; o endpoint é api_jsonrpc.php; a autenticação pode usar API token ou token de sessão obtido por user.login; permissões dependem de usuário, role e grupos. A referência oficial contém APIs para configuração, monitoramento, services/SLA, usuários, tokens, proxies, audit log e outras famílias.

Linha Zabbix 7.4

A API permanece baseada em JSON-RPC e suporta API tokens e controle por roles. Automatizações devem ser idempotentes, auditáveis e usar privilégio mínimo.