Table of Contents

20 API

20 API

Descripción general

La API de Zabbix le permite recuperar y modificar programáticamente la configuración de Zabbix y proporciona acceso a datos históricos. Se utiliza ampliamente para:

crear nuevas aplicaciones para trabajar con Zabbix;
integrar Zabbix en un software de terceros;
automatizar tareas rutinarias.

La API de Zabbix es una API basada en HTTP y se distribuye como parte del frontend web. Utiliza el protocolo JSON-RPC 2.0, lo que significa dos cosas:

la API consta de un conjunto de métodos separados;
las solicitudes y respuestas entre los clientes y la API se codifican utilizando el formato JSON.

Para obtener más información sobre el protocolo y JSON, consulte la especificación JSON-RPC 2.0 y la página principal del formato JSON.

Para obtener más información sobre cómo integrar la funcionalidad de Zabbix en sus aplicaciones Python, consulte la biblioteca Python zabbix_utils para la API de Zabbix.

Estructura

La API consta de varios métodos que están agrupados 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 de equipo y se utiliza para crear nuevos equipos. Históricamente, las APIs a veces se denominan "clases".

La mayoría de las APIs contienen al menos cuatro métodos: get, create, update y delete para recuperar, crear, actualizar y eliminar datos respectivamente, pero algunas APIs pueden proporcionar un conjunto de métodos totalmente diferente.

Realización de solicitudes

Una vez que haya configurado la interfaz web, puede utilizar solicitudes HTTP remotas para llamar a la API. Para ello, debe enviar solicitudes HTTP POST al archivo api_jsonrpc.php ubicado en el directorio de la interfaz web. Por ejemplo, si su interfaz web de Zabbix está instalada en https://example.com/zabbix, una solicitud HTTP para llamar al método apiinfo.version podría verse así:

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 encabezado Content-Type establecido en uno de estos valores: application/json-rpc, application/json o 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 de la API que se está llamando;
params - los parámetros que se pasarán al método de la 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": "8.0.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

La siguiente sección le guiará a través de algunos ejemplos de uso con mayor detalle.

Autenticación

Para acceder a cualquier dato en Zabbix, debe:

usar un token de API existente (creado en la interfaz de Zabbix o utilizando la API de Token);
usar 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 el usuario estándar Admin, la solicitud JSON sería la siguiente:

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 debería contener el token de autenticación del usuario:

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

Métodos de autorización

Por cabecera "Authorization"

Todas las solicitudes a la API requieren autenticación o un token de API. Puede proporcionar las credenciales utilizando la cabecera Authorization en la solicitud:

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

Si experimenta problemas de autenticación, consulte Reenvío de la cabecera Authorization.

La API de Zabbix acepta las cabeceras sin distinguir mayúsculas de minúsculas (por ejemplo, authorization, Authorization y AUTHORIZATION se tratan igual).

La cabecera Authorization es compatible en solicitudes de origen cruzado (CORS).

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

Recuperar equipos

Ahora tienes un token de autenticación de usuario válido que puede usarse para acceder a los datos en Zabbix. Por ejemplo, puedes usar el método host.get para recuperar los IDs, 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, puedes pasar la consulta en el argumento --data.

data.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 razones de rendimiento, siempre se recomienda listar las propiedades del objeto que deseas recuperar. Así evitarás recuperar todo.

Creando una nueva métrica

Ahora, cree una nueva métrica en el equipo "Zabbix server" utilizando los datos que ha obtenido de la solicitud host.get anterior. Esto se puede hacer utilizando 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":"Espacio libre en disco en /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 puede usarse para referenciar 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 arreglos de objetos y crear múltiples métricas con una sola llamada a la API.

Creación de múltiples disparadores

Así, si los métodos de creación aceptan arrays, puede añadir múltiples disparadores, por ejemplo, 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":"La carga del procesador es demasiado alta en {HOST.NAME}","expression":"last(/Linux server/system.cpu.load[percpu,avg1])>5",},{"description":"Demasiados procesos en {HOST.NAME}","expression":"avg(/Linux server/proc.num[],5m)>300",}],"id":4}'

La respuesta exitosa contendrá los IDs de los disparadores recién creados:

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

Actualización de 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 arreglos de objetos y actualizar múltiples métricas con una sola llamada a la API.

Actualización de múltiples disparadores

Habilite varios disparadores 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 IDs de los disparadores actualizados:

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

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

Manejo de errores

Hasta el momento, todo lo que has intentado ha funcionado correctamente. Pero, ¿qué sucedería si intentaras realizar una llamada incorrecta a la API? Intenta crear otro equipo llamando a host.create pero omitiendo el parámetro obligatorio 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 respuesta contendrá la propiedad error con los siguientes datos:

code - un código de error;
message - un resumen breve del error;
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 de espera de sesión agotado o al intentar acceder a objetos inexistentes. Tu aplicación debe ser capaz de manejar este tipo de errores de manera adecuada.

Versiones de la API

Para simplificar la gestión de versiones de la API, desde Zabbix 2.0.4, la versión de la API coincide con la versión de Zabbix en sí. Puede utilizar el método apiinfo.version para averiguar la versión de la API con la que está trabajando. Esto puede ser útil para ajustar su aplicación y utilizar funciones específicas de la versión.

Zabbix garantiza la compatibilidad de las funciones dentro de una versión principal. Al realizar cambios incompatibles entre versiones principales, Zabbix normalmente deja las funciones antiguas como obsoletas en la siguiente versión y solo las elimina en la versión posterior. Ocasionalmente, Zabbix puede eliminar funciones entre versiones principales sin proporcionar compatibilidad hacia atrás. Es importante que nunca dependa de ninguna función obsoleta y migre a alternativas más recientes lo antes posible.

Puede seguir todos los cambios realizados en la API en el registro de cambios de la API.

Lectura adicional

Ahora tienes suficiente conocimiento para comenzar a trabajar con la API de Zabbix, sin embargo, no te detengas aquí. Para una lectura adicional, se recomienda que consultes la lista de APIs disponibles.

Documentation