Apéndice 1. Comentario de referencia

Notación

Tipos de datos

La API de Zabbix admite los siguientes tipos de datos como entrada:

Tipo Descripción
booleano Un valor booleano, acepta true o false.
flag El valor se considera true si se pasa y no es igual a null; en caso contrario, se considera false.
entero Un número entero.
float Un número de punto flotante.
cadena Una cadena de texto.
texto Una cadena de texto más larga.
marca de tiempo Una marca de tiempo de Unix.
matriz Una secuencia ordenada de valores, es decir, una matriz simple.
objeto Una matriz asociativa.
consulta Un valor que define qué datos deben devolverse.

Se puede definir como una matriz de nombres de propiedades para devolver solo propiedades específicas, o como uno de los valores predefinidos:
extend - devuelve todas las propiedades del objeto;
count: devuelve el número de registros recuperados, admitido sólo por determinadas subselecciones.

La API de Zabbix siempre devuelve solamente valores como cadenas o matrices.

Comportamiento de la propiedad

Algunas de las propiedades del objeto están marcadas con etiquetas cortas para describir su comportamiento. Se utilizan las siguientes etiquetas:

  • solo lectura: el valor de la propiedad se establece automáticamente y el usuario no puede definirlo ni cambiarlo, incluso en algunas condiciones específicas. (por ejemplo, solo lectura para objetos heredados u objetos descubiertos);
  • solo escritura: el valor de la propiedad se puede establecer, pero no se puede acceder a él después;
  • constante - el valor de la propiedad se puede establecer al crear un objeto, pero no se puede cambiar después;
  • compatible: no es necesario establecer el valor de la propiedad, pero se permite establecerlo en algunas condiciones específicas (por ejemplo, compatible si type está configurado en "Verificación simple", "Verificación externa", "Agente SSH", "Agente TELNET" o "Agente HTTP");
  • obligatorio: se requiere establecer el valor de la propiedad para todas las operaciones (excepto las operaciones de obtención) o en algunas condiciones específicas (por ejemplo, obligatorio para operaciones de creación; obligatorio si operationtype está configurado en "script global" y opcommand_hst no está configurado).

Para operaciones de actualización, una propiedad se considera "establecida" cuando se configura durante la operación de actualización.

Las propiedades que no están marcadas con etiquetas son opcionales.

Comportamiento del parámetro

Algunos de los parámetros de operación están marcados con etiquetas cortas para describir su comportamiento durante la operación. Se utilizan las siguientes etiquetas:

  • solo lectura: el valor del parámetro se establece automáticamente y el usuario no puede definirlo ni cambiarlo, incluso en algunas condiciones específicas. (por ejemplo, solo lectura para objetos heredados u objetos descubiertos);
  • solo escritura: el valor del parámetro se puede configurar, pero no se puede acceder a él después;
  • compatible: no es necesario establecer el valor del parámetro, pero se permite establecerlo en algunas condiciones específicas (por ejemplo, compatible si el status del objeto Proxy está establecido en "proxy pasivo");
  • obligatorio: es necesario establecer el valor del parámetro.

Los parámetros que no están marcados con etiquetas son opcionales.

Valor de ID reservado "0"

El valor de ID reservado "0" se puede utilizar para filtrar elementos y eliminar objetos referenciados. Por ejemplo, para eliminar un proxy al que se hace referencia de un equipo, proxy_hostid debe establecerse en 0 ("proxy_hostid": "0") o para filtrar equipos monitoreados por la opción de servidor proxyids deben establecerse en 0 ("proxyids": "0").

Parámetros comunes del método "get"

Todos los métodos "get" admiten los siguientes parámetros:

Parámetro Tipo Descripción
countOutput booleano Devuelve la cantidad de registros en el resultado en lugar de los datos reales.
editable booleano Si se establece en "true", devuelve solo los objetos para los que el usuario tiene permisos de escritura.

Predeterminado: "false".
excludeSearch booleano Devuelve los resultados que no coinciden con los criterios dados en el parámetro "search".
filter objeto Devuelve solo los resultados que coinciden exactamente con el filtro dado.

Acepta un objeto, donde las claves son nombres de propiedades y los valores son un valor único o una matriz de valores con los que comparar.

No admite propiedades de "text" tipo de datos.
limit entero Limita la cantidad de registros que se devuelven.
output query Propiedades de objeto que se devolverán.

Predeterminado: extend.
preservekeys boolean Usa los identificadores como claves en la matriz resultante.
search objeto Devuelve los resultados que coinciden con el patrón dado (sin distinguir entre mayúsculas y minúsculas).

Acepta un objeto, donde las claves son nombres de propiedades y los valores son cadenas para buscar. Si no se proporcionan opciones adicionales, se realizará una búsqueda LIKE "%…%".

Solo admite propiedades de string y text tipo de datos.
searchByAny booleano Si se establece en true, devuelve los resultados que coinciden con cualquiera de los criterios dados en el parámetro filter o search en lugar de todos ellos.

Predeterminado: false.
searchWildcardsEnabled booleano Si se establece en true, habilita el uso de "*" como carácter comodín en el parámetro search.

Valor predeterminado: false.
sortfield cadena/matriz Ordene el resultado según las propiedades proporcionadas. Consulte la descripción de un método de obtención de API específico para obtener una lista de propiedades que se pueden usar para ordenar. Las macros no se expanden antes de ordenar.

Si no se especifica ningún valor, los datos se devolverán sin ordenar.
sortorder cadena/matriz Orden de ordenación. Si se pasa una matriz, cada valor se corresponderá con la propiedad correspondiente proporcionada en el parámetro sortfield.

Valores posibles:
ASC - (predeterminado) ascendente;
DESC - descendente.
startSearch booleano El parámetro search comparará el comienzo de los campos, es decir, realizará una búsqueda LIKE "…%" en su lugar.

Se ignora si searchWildcardsEnabled está establecido en true.

Ejemplos

Verificación de permisos de usuario

¿Tiene el usuario permiso para escribir en equipos cuyos nombres comiencen por "MySQL" o "Linux"?

Solicitud:

{
"jsonrpc": "2.0",
"method": "host.get",
"params": {
"countOutput": true,
"search": {
"host": ["MySQL", "Linux"]
},
"editable": true,
"startSearch": true,
"searchByAny": true
},
"id": 1
}

Respuesta:

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

Resultado cero significa que no hay equipos con permisos de lectura/escritura.

Recuento de discrepancias

Cuente el número de equipos cuyos nombres no contienen la subcadena "ubuntu"

Solicitud:

{
"jsonrpc": "2.0",
"method": "host.get",
"params": {
"countOutput": true,
"search": {
"host": "ubuntu"
},
"excludeSearch": true
},
"id": 1
}

Respuesta:

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

Búsqueda de equipos usando comodines

Encuentre equipos cuyos nombres contengan la palabra "server" y tenga puertos de interfaz "10050" o "10071". Ordene el resultado por nombre de equipo en orden descendente y limítelo a 5 equipos.

Solicitud:

{
"jsonrpc": "2.0",
"method": "host.get",
"params": {
"output": ["hostid", "host"],
"selectInterfaces": ["port"],
"filter": {
"port": ["10050", "10071"]
},
"search": {
"host": "*server*"
},
"searchWildcardsEnabled": true,
"searchByAny": true,
"sortfield": "host",
"sortorder": "DESC",
"limit": 5
},
"id": 1
}

Respuesta:

{
"jsonrpc": "2.0",
"result": [
{
"hostid": "50003",
"host": "WebServer-Tomcat02",
"interfaces": [
{
"port": "10071"
}
]
},
{
"hostid": "50005",
"host": "WebServer-Tomcat01",
"interfaces": [
{
"port": "10071"
}
]
},
{
"hostid": "50004",
"host": "WebServer-Nginx",
"interfaces": [
{
"port": "10071"
}
]
},
{
"hostid": "99032",
"host": "MySQL server 01",
"interfaces": [
{
"port": "10050"
}
]
},
{
"hostid": "99061",
"host": "Linux server 01",
"interfaces": [
{
"port": "10050"
}
]
}
],
"id": 1
}

Búsqueda de equipos usando comodines con "preservekeys"

Si agrega el parámetro "preservekeys" a la solicitud anterior, el resultado se devuelve como una matriz asociativa, donde las claves son la identificación de los objetos.

Solicitud:

{
"jsonrpc": "2.0",
"method": "host.get",
"params": {
"output": ["hostid", "host"],
"selectInterfaces": ["port"],
"filter": {
"port": ["10050", "10071"]
},
"search": {
"host": "*server*"
},
"searchWildcardsEnabled": true,
"searchByAny": true,
"sortfield": "host",
"sortorder": "DESC",
"limit": 5,
"preservekeys": true
},
"id": 1
}

Respuesta:

{
"jsonrpc": "2.0",
"result": {
"50003": {
"hostid": "50003",
"host": "WebServer-Tomcat02",
"interfaces": [
{
"port": "10071"
}
]
},
"50005": {
"hostid": "50005",
"host": "WebServer-Tomcat01",
"interfaces": [
{
"port": "10071"
}
]
},
"50004": {
"hostid": "50004",
"host": "WebServer-Nginx",
"interfaces": [
{
"port": "10071"
}
]
},
"99032": {
"hostid": "99032",
"host": "MySQL server 01",
"interfaces": [
{
"port": "10050"
}
]
},
"99061": {
"hostid": "99061",
"host": "Linux server 01",
"interfaces": [
{
"port": "10050"
}
]
}
},
"id": 1
}