Table of Contents

19 API

19 API

Visión general

El API de Zabbix nos permite recuperar y modificar de forma programada la configuración de Zabbix y provee acceso a los datos históricos. Está ampliamente usado para :

Crear nuevas aplicaciones para trabajar con Zabbix;
Integrar Zabbix con software de terceras partes;
Automatizar tareas rutinarias.

El API de Zabbix es un API basado en web y está integrado como parte de la interfaz de la web. Usa el protocolo JSON-RCP 2.0 lo cual significa dos cosas:

El API consiste en un conjunto de métodos separados;
Solicitudes y respuestas entre los clientes y el API están codificados usando el formato JSON.

Más información sobre el protocolo y JSON puede ser encontrada en Especificación JSON-RCP 2.0 y [Formato JSON]http://json.org/).

Estructura

La API consta de una serie de métodos que se agrupan nominalmente en APIs separadas. Cada uno de los métodos realiza una tarea específica. Por ejemplo, el método host.create pertenece a la API host y es usado para crear nuevos equipos. Históricamente las APIs a veces se denominan "clases".

La gran mayoria de las APIs contienen al menos cuatro métodos: get, create, update y delete para recuperar, crear, actualizar y borrar datos respectivamente, pero algunas de las APIs pueden proporcionar un conjunto totalmente distinto de métodos.

Realización de solicitudes

Una vez tenga configurada la interfaz, puede usar solicitudes HTTP remotas para llamar a la API. Para hacerlo, tiene que enviar solicitudes HTTP POST al archivo api_jsonrpc.php que está ubicado en el directorio del interfaz de usuario web. Por ejemplo si su interfaz está instalada en http://company.com/zabbix*, la solicitud para llamar al método apiinfo.version puede ser como esta:

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

La solicitud debe tener el el encabezado Content-Type con uno de estos valores establecidos: application/json-rpc, application/jsonor application/jsonrequest.

El objeto de solicitud contiene las siguientes propiedades:

jsonrpc: la versión del protocolo JSON-RPC utilizada por la API (la API de Zabbix implementa JSON-RPC versión 2.0);
method: el método API que se llama;
params: los parámetros que se pasarán al método API;
id: un identificador arbitrario de la solicitud.

Si la solicitud es correcta, la respuesta devuelta por la API debería verse así:

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

El objeto de respuesta, a su vez, contiene las siguientes propiedades:

jsonrpc - la versión del protocolo JSON-RPC;
result: los datos devueltos por el método;
id: un identificador de la solicitud correspondiente.

Ejemplo de flujo de trabajo

En la siguiente sección vamos a guiarlo a través de algunos ejemplos con mayor detalle.

Autenticación

Para acceder a cualquier dato en Zabbix, necesita:

usar un token API existente (creado en la interfaz de Zabbix o usando el Token API);
utilizar un token de autenticación obtenido con el método user.login.

Por ejemplo, si desea obtener un nuevo token de autenticación iniciando sesión como usuario Admin estándar, entonces una solicitud JSON se vería así:

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

Si proporcionó las credenciales correctamente, la respuesta devuelta por la API debe contener el token de autenticación del usuario:

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

Métodos de autorización

Por encabezado "Autorización"

Todas las solicitudes de API requieren una autenticación o un token de API. Puede proporcionar las credenciales utilizando el encabezado de solicitud "Authorization":

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

Por propiedad "auth"

La propiedad "auth" puede autorizar una solicitud de API.

Tenga en cuenta que la propiedad "auth" está en desuso. Se eliminará en futuras versiones.

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

Por galleta Zabbix

Una cookie "zbx_session" se utiliza para autorizar una solicitud de API desde la interfaz de usuario de Zabbix realizada utilizando JavaScript (desde un módulo o un widget personalizado).

Recuperando equipos

Ahora tiene un token de autenticación de usuario válido que puede usar para acceder a los datos en Zabbix. Por ejemplo, puede utilizar el Método host.get para recuperar los ID, nombres de equipo e interfaces de todos los equipos configurados:

Solicitud:

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 es un archivo que contiene una consulta JSON. En lugar de un archivo, puede pasar la consulta en el argumento --data.

datos.json

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

El objeto de respuesta contendrá los datos solicitados sobre los equipos:

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

Por motivos de rendimiento, siempre se recomienda enumerar las propiedades del objeto que desea recuperar. Así, evitará recuperarlo todo.

Creando una nueva métrica

Ahora, cree una nueva métrica en el equipo "Zabbix server" usando los datos que ha obtenido del host.get en la solicitud anterior. Esto se puede hacer usando el 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}'

Una respuesta exitosa contendrá el ID de la métrica recién creada, que se puede utilizar para hacer referencia a la métrica en las siguientes solicitudes:

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

El método item.create así como otros métodos de creación también pueden aceptar matrices de objetos y crear varios elementos con una única llamada a la API.

Creando múltiples iniciadores

Entonces, si los métodos de creación aceptan matrices, podemos agregar múltiples iniciadores así:

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

Una respuesta exitosa contendrá los ID de los iniciadores recién creados:

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

Actualizando una métrica

Habilite una métrica estableciendo su estado en "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}'

La respuesta exitosa contendrá el ID de la métrica actualizada:

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

El método item.update así como otros métodos de actualización también pueden aceptar matrices de objetos y actualizar varias métricas con una única llamada a la API.

Actualización de múltiples iniciadores

Habilite múltiples iniciadores estableciendo su estado en "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}'

La respuesta exitosa contendrá los ID de los iniciadores actualizados:

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

Este es el método preferido de actualización. Algunos métodos API, como host.massupdate, permiten escribir un código más simple. Sin embargo, no se recomienda utilizar estos métodos ya que se eliminarán en versiones futuras.

Manejo de errores

Hasta el momento todo lo que ha probado ha funcionado bien. Pero ¿qué sucede si intenta realizar una llamada incorrecta a la API? Intentar crear otro equipo llamando a host.create pero omitiendo el parámetro obligatorio de 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}'

La respuesta contendrá entonces un mensaje de error:

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

Si se ha producido un error, en lugar de la propiedad result, el objeto de la respuesta contendrá la propiedad error con los siguientes datos:

code - un código de error;
message: un breve resumen de errores;
data: un mensaje de error más detallado.

Los errores pueden ocurrir en varios casos, como por ejemplo, al usar valores de entrada incorrectos, un tiempo excedido de espera de sesión o intentar acceder a objetos no existentes. Su aplicación debería poder manejar correctamente este tipo de errores.

Versiones de API

Para simplificar el versionado de API, desde Zabbix 2.0.4, la versión de la API coincide con la versión misma de Zabbix . Puede usar el método apiinfo.version para encontrar la versión de la API con la que está trabajando. Esto puede ser muy útil para ajustar su aplicación y usar las funciones especificas de la versión.

Zabbix garantiza la compatibilidad con versiones anteriores en una misma versión principal. Cuando hacemos cambios incompatibles entre versiones principales, solemos dejar las características anteriores como obsoletas en la nueva versión, y solo las eliminamos después del lanzamiento de la siguiente versión. Ocasionalmente podríamos eliminar funciones entre versiones principales sin proveer compatibilidad. Es importante que nunca confíe en ninguna función obsoleta y actualice cuanto antes a las nuevas alternativas.

Puede seguir todos los cambios de la API en el API changelog.

Otras lecturas

Ahora ya sabe suficiente para empezar a trabajar con las API en Zabbix, pero no se detenga aquí. Para más información le sugerimos que eche un vistazo a la lista de API disponibles.

Documentation