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
ID Un identificador único utilizado para hacer referencia a una entidad.
booleano Un valor booleano (ya sea verdadero o falso).
flag Un valor que se considera "verdadero" si se pasa y no es igual a "nulo"; de lo contrario, el valor se considera "falso".
entero Un número entero.
float Un número de punto flotante.
cadena Una cadena de texto.
text Una cadena de texto más larga.
marca de tiempo Una marca de tiempo de Unix.
matriz Una secuencia ordenada de valores (una matriz simple).
objeto Una matriz asociativa.
consulta Un valor que define los datos que se devolverán. El valor 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, admitidos sólo por ciertas subselecciones.

La API de Zabbix siempre devuelve valores como cadenas o solo 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 no puede ser definido ni modificado por el usuario, incluso en algunas condiciones específicas (por ejemplo, solo lectura para objetos heredados u objetos descubiertos);
  • solo escritura: el valor de la propiedad puede establecerse, pero no puede accederse a él después;
  • constante: el valor de la propiedad puede establecerse al crear un objeto, pero no puede modificarse después;
  • soportada: no es obligatorio establecer el valor de la propiedad, pero se permite establecerlo en algunas condiciones específicas (por ejemplo, soportada si type se establece en "Comprobación simple", "Comprobación externa", "Agente SSH", "Agente TELNET" o "Agente HTTP"); sin embargo, tenga en cuenta que las propiedades soportadas aún pueden establecerse en sus valores predeterminados independientemente de las condiciones;
  • requerida: es obligatorio establecer el valor de la propiedad para todas las operaciones (excepto las operaciones de obtención) o en algunas condiciones específicas (por ejemplo, requerida para operaciones de creación; requerida si operationtype se establece en "script global" y opcommand_hst no está establecido).

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

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

Comportamiento de los parámetros

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

  • solo-lectura: el valor del parámetro se establece automáticamente y no puede ser definido ni cambiado por el usuario, incluso en algunas condiciones específicas (por ejemplo, solo-lectura para objetos heredados u objetos descubiertos);
  • solo-escritura: el valor del parámetro puede establecerse, pero no puede accederse después;
  • soportado: no se requiere que se establezca el valor del parámetro, pero se permite establecerlo en algunas condiciones específicas (por ejemplo, soportado si operating_mode del objeto Proxy se establece en "proxy pasivo"); sin embargo, tenga en cuenta que los parámetros soportados aún pueden establecerse en sus valores predeterminados independientemente de las condiciones;
  • requerido: se requiere que se establezca 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, proxyid debe establecerse en 0 ("proxyid": "0") o en el filtro de equipos monitoreados por la opción de servidor proxyids deben establecerse en 0 ("proxyids": "0").

Parámetros comunes de los métodos "get"

Los siguientes parámetros son compatibles con todos los métodos get:

Parámetro Tipo Descripción
countOutput boolean Devuelve el número de registros en el resultado en lugar de los datos reales.
editable boolean Si se establece en true, devuelve solo los objetos sobre los que el usuario tiene permisos de escritura.

Por defecto: false.
excludeSearch boolean Devuelve resultados que no coinciden con los criterios dados en el parámetro search.
filter object Devuelve solo aquellos resultados que coinciden exactamente con el filtro dado.

Acepta un objeto, donde las claves son nombres de propiedades (por ejemplo, propiedades del objeto Host en host.get, propiedades del objeto Item en item.get, etc.), y los valores son un único valor o un array de valores con los que comparar.

No admite propiedades del tipo de dato text data type.

Tenga en cuenta que algunos métodos tienen una funcionalidad específica para este parámetro, que se describe en la página del método (por ejemplo, el parámetro filter en host.get también admite propiedades de la interfaz de Host).
limit integer Limita el número de registros devueltos.
output query Propiedades del objeto que se devolverán.

Tenga en cuenta que el ID del objeto (es decir, hostid, itemid, etc.) siempre se incluye en la respuesta, incluso si no se especifica en el parámetro output.

Por defecto: extend.
preservekeys boolean Utiliza los IDs como claves en el array resultante.
search object Devuelve resultados que coinciden con el patrón dado (no distingue mayúsculas de minúsculas).

Acepta un objeto, donde las claves son nombres de propiedades (por ejemplo, propiedades del objeto Host en host.get, propiedades del objeto Item en item.get, etc.), y los valores son cadenas a buscar. Si no se dan opciones adicionales, esto realizará una búsqueda LIKE "%…%".

Solo admite propiedades de tipo de dato string y text data type.

Tenga en cuenta que algunos métodos tienen una funcionalidad específica para este parámetro, que se describe en la página del método (por ejemplo, el parámetro search en host.get también admite propiedades de la interfaz de Host).
searchByAny boolean Si se establece en true, devuelve resultados que coinciden con cualquiera de los criterios dados en el parámetro filter o search en lugar de todos ellos.

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

Por defecto: false.
sortfield string/array Ordena el resultado por las propiedades dadas. Consulte la descripción de un método get específico de la API para obtener una lista de las propiedades que se pueden utilizar 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 string/array Orden de clasificación. Si se pasa un array, cada valor se emparejará con la propiedad correspondiente dada en el parámetro sortfield.

Valores posibles:
ASC - (por defecto) ascendente;
DESC - descendente.
startSearch boolean 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
}