Table of Contents

19 API

19 API

Descripción general

La API de Zabbix le permite recuperar y modificar mediante programación la configuración de Zabbix y proporciona acceso a datos históricos. Es ampliamente utilizada 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 envía como parte de la interfaz 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] (http://www.jsonrpc.org/specification) y la [página de inicio del formato JSON] (http://json.org/).

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

Realizando solicitudes

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

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: aplicación/json-rpc, aplicación/json o aplicación/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 parecerse a esto:

{
            "jsonrpc": "2.0",
            "result": "7.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

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