Documentation
Table of Contents
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 usada para crear nuevos host. Históricamente las APIs a veces se denominan "classes".
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 hacerlo, debe enviar solicitudes HTTP POST al archivo api_jsonrpc.php ubicado en el directorio frontend. Por ejemplo, si su interfaz Zabbix está instalada en http://example.com/zabbix, la solicitud HTTP para llamar al método apiinfo.version puede verse así:
POST http://example.com/zabbix/api_jsonrpc.php HTTP/1.1
Content-Type: application/json-rpc
{
"jsonrpc": "2.0",
"method": "apiinfo.versión",
"id": 1,
"auth": nula,
"params": {}
}La solicitud debe tener el encabezado Content-Type establecido en uno de estos valores: application/json-rpc, application/json o application/jsonrequest.
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í:
{
"jsonrpc": "2.0",
"método": "usuario.iniciar sesión",
"parámetros": {
"nombre de usuario": "Administrador",
"contraseña": "zabbix"
},
"identificación": 1,
"autenticación": nula
}Echemos un vistazo más de cerca al objeto de solicitud. Tiene lo siguiente propiedades:
jsonrpc: la versión del protocolo JSON-RPC utilizada por la API; la API de Zabbix implementa JSON-RPC versión 2.0;método: el método API que se llama;params: parámetros que se pasarán al método API;id: un identificador arbitrario de la solicitud;auth: un token de autenticación de usuario; Como aún no tenemos uno, está configurado en "nulo".
Si proporcionó las credenciales correctamente, la respuesta devuelta por el La API contendrá el token de autenticación del usuario:
El objeto de respuesta a su vez contiene las siguientes propiedades:
jsonrpc- nuevamente, la versión del protocolo JSON-RPC;resultado: los datos devueltos por el método;id- identificador de la solicitud correspondiente.
Recuperando anfitriones
Ahora tenemos un token de autenticación de usuario válido que se puede usar para acceder los datos en Zabbix. Por ejemplo, usemos el host.get método para recuperar los ID, nombres de host e interfaces de todos los configurados hosts:
{
"jsonrpc": "2.0",
"método": "host.get",
"parámetros": {
"producción": [
"hostid",
"anfitrión"
],
"seleccionarInterfaces": [
"id de interfaz",
"ip"
]
},
"identificación": 2,
"autorización": "0424bd59b807674191e7d77572075f33"
}Tenga en cuenta que la propiedad auth ahora está establecida en el token de autenticación que hemos obtenido llamando usuario.login.
El objeto de respuesta contendrá los datos solicitados sobre los hosts:
{
"jsonrpc": "2.0",
"resultado": [
{
"hostid": "10084",
"anfitrión": "servidor Zabbix",
"interfaces": [
{
"interfaceid": "1",
"ip": "127.0.0.1"
}
]
}
],
"identificación": 2
}Por motivos de rendimiento, recomendamos enumerar siempre los propiedades del objeto que desea recuperar y evitar recuperar todo.
Creando un nuevo elemento
Vamos a crear un nuevo elemento en "Zabbix server" usando los datos que hemos obtenido del anterior host.get solicitud. Esto se puede hacer usando el item.create método:
{
"jsonrpc": "2.0",
"método": "elemento.crear",
"parámetros": {
"name": "Espacio libre en disco en /home/joe/",
"key_": "vfs.fs.tamaño[/home/joe/,gratis]",
"hostid": "10084",
"tipo": 0,
"tipo_valor": 3,
"interfaceid": "1",
"retraso": 30
},
"autorización": "0424bd59b807674191e7d77572075f33",
"identificación": 3
}Una respuesta exitosa contendrá la ID del elemento recién creado, que se puede utilizar para hacer referencia al artículo en las siguientes solicitudes:
El método item.create así como otros métodos de creación también puede aceptar matrices de objetos y crear varios elementos con una API llamar.
Creando múltiples disparadores
Entonces, si los métodos de creación aceptan matrices, podemos agregar múltiples disparadores así:
{
"jsonrpc": "2.0",
"método": "trigger.create",
"parámetros": [
{
"description": "La carga del procesador es demasiado alta en {HOST.NAME}",
"expresión": "último(/servidor Linux/sistema.cpu.load[percpu,avg1])>5",
},
{
"description": "Demasiados procesos en {HOST.NAME}",
"expresión": "promedio(/servidor Linux/proc.num[],5m)>300",
}
],
"autorización": "0424bd59b807674191e7d77572075f33",
"identificación": 4
}Una respuesta exitosa contendrá los ID de los recién creados desencadenantes:
Actualización de un elemento
Habilite un elemento, es decir, establezca su estado en "0":
{
"jsonrpc": "2.0",
"método": "item.update",
"parámetros": {
"itemid": "10092",
"estado": 0
},
"autorización": "0424bd59b807674191e7d77572075f33",
"identificación": 5
}Una respuesta exitosa contendrá el ID del elemento actualizado:
El método item.update así como otros métodos de actualización también puede aceptar matrices de objetos y actualizar varios elementos con una API llamar.
Actualización de múltiples disparadores
Habilite múltiples disparadores, es decir, establezca su estado en 0:
{
"jsonrpc": "2.0",
"método": "trigger.update",
"parámetros": [
{
"triggerid": "13938",
"estado": 0
},
{
"triggerid": "13939",
"estado": 0
}
],
"autorización": "0424bd59b807674191e7d77572075f33",
"identificación": 6
}Una respuesta exitosa contendrá los ID de los disparadores actualizados:
Este es el método preferido de actualización. Algunas API métodos como host.massupdate permiten escribir código más simple, pero es No se recomienda utilizar esos métodos, ya que se eliminarán en el lanzamientos futuros.
Manejo de errores
Hasta ese momento todo lo que hemos probado ha funcionado bien. Pero que Qué pasa si tratamos de hacer una llamada incorrecta a la API? intentemos crear otro host llamando host.create pero omitiendo el parámetro groups obligatorio.
{
"jsonrpc": "2.0",
"método": "host.create",
"parámetros": {
"anfitrión": "Servidor Linux",
"interfaces": [
{
"tipo 1,
"principal": 1,
"usoip": 1,
"ip": "192.168.3.1",
"DNS": "",
"puerto": "10050"
}
]
},
"identificación": 7,
"autorización": "0424bd59b807674191e7d77572075f33"
}La respuesta contendrá un mensaje de error:
{
"jsonrpc": "2.0",
"error": {
"código": -32602,
"mensaje": "Parámetros no válidos.",
"data": "No hay grupos para el host \"servidor Linux\"."
},
"identificación": 7
}Si ocurriera un error, en lugar de la propiedad resultado, la respuesta El objeto contendrá una propiedad error con los siguientes datos:
código- un código de error;mensaje- un breve resumen del error;data- un mensaje de error más detallado.
Los errores pueden ocurrir en diferentes casos, como por ejemplo, usando una entrada incorrecta valores, un tiempo de espera de la sesión o intentar acceder a objetos inexistentes. Su La 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 tu aplicación y usar las funciones especificas de la versión.
Garantizamos compatibilidad con versiones anteriores en una versión principal. Cuando dejamos versiones incompatibles por cambio en versiones principales, por lo general dejamos las funciones antiguas como obsoletas en la siguiente versión, y solo las eliminamos después del lanzamiento de esta. 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.
Puedes seguir todos los cambios de la API en el API changelog.
Otras lecturas
Ahora ya sabes suficiente para empezar a trabajar con las API en Zabbix, pero no te detengas aquí. Para más información te sugerimos que eches un vistazo a la list of available APIs.