Table of Contents
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. |
| boolean | Un valor booleano (ya sea true o false). |
| flag | Un valor que se considera true si se pasa y no es igual a null; de lo contrario, el valor se considera false. |
| integer | Un número entero. |
| float | Un número de punto flotante. |
| string | Una cadena de texto. |
| text | Una cadena de texto más larga. |
| timestamp | Una marca de tiempo Unix. |
| array | Una secuencia ordenada de valores (un array simple). |
| object | Un array asociativo. |
| query | Un valor que define los datos a devolver. El valor puede definirse como un array 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, solo es compatible con ciertos subselects. |
La API de Zabbix siempre devuelve valores solo como cadenas o arrays.
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 o cambiado 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 después;
- constante: el valor de la propiedad puede establecerse al crear un objeto, pero no puede cambiarse después;
- soportado: no es obligatorio establecer el valor de la propiedad, pero se permite establecerlo en algunas condiciones específicas (por ejemplo, soportado si
typese 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; - requerido: es obligatorio establecer el valor de la propiedad para todas las operaciones (excepto las operaciones get) o en algunas condiciones específicas (por ejemplo, requerido para operaciones de creación; requerido si
operationtypese establece en "script global" yopcommand_hstno está establecido).
Para las operaciones de actualización, una propiedad se considera como "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 para la operación. Se utilizan las siguientes etiquetas:
- solo-lectura - el valor del parámetro se establece automáticamente y no puede ser definido o 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 el valor del parámetro se establezca, pero se permite establecerlo en algunas condiciones específicas (por ejemplo, soportado si
operating_modedel objeto Proxy se establece en "proxy pasivo"); tenga en cuenta, sin embargo, que los parámetros soportados aún pueden establecerse en sus valores predeterminados independientemente de las condiciones; - requerido - se requiere que el valor del parámetro se establezca.
Los parámetros que no están marcados con etiquetas son opcionales.
Valor de ID reservado "0"
El valor de ID reservado "0" puede usarse para filtrar elementos y para eliminar objetos referenciados. Por ejemplo, para eliminar un proxy referenciado de un equipo, proxyid debe establecerse en 0 ("proxyid": "0") o para filtrar equipos monitorizados por la opción server, proxyids debe 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 Equipo en host.get, propiedades del objeto Métrica en item.get, etc.), y los valores son un único valor o un array de valores con los que comparar.No admite propiedades de 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 equipo). |
| limit | integer | Limita el número de registros devueltos. |
| output | query | Propiedades del objeto que se devolverán. 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 Equipo en host.get, propiedades del objeto Métrica 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 equipo). |
| 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 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 | string/array | Orden de la 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. |
Indicadores de origen de entidad
Los métodos Get devuelven una propiedad flags para las entidades relacionadas con el descubrimiento de bajo nivel (regla LLD/prototipo de regla LLD, métrica/prototipo de métrica, etc). Esta propiedad es útil para indicar si la entidad ha sido descubierta o no, ya que la edición de entidades descubiertas está limitada.
La propiedad flags devuelve un resultado basado en una combinación (operación "+") de estos valores:
| Valor | Descripción |
|---|---|
| 0 | Entidad base (métrica, disparador, gráfico, equipo) |
| 1 | Regla de descubrimiento de bajo nivel |
| 2 | Cualquier prototipo (prototipo de métrica, prototipo de disparador, prototipo de regla LLD, etc) |
| 4 | Entidad descubierta (métrica, disparador, gráfico, equipo, regla LLD descubierta) |
El valor combinado devuelto por la propiedad flags puede ser:
| Valor | Combinación de | Descripción |
|---|---|---|
| 0 | 0 | Entidad simple (métrica, disparador, gráfico, equipo). |
| 2 | 2 | Prototipo de entidad (prototipo de métrica, prototipo de disparador, etc). |
| 6 | 2+4 | Métrica, disparador, gráfico, equipo descubierto (convertido desde prototipo). |
| 1 | 1 | Regla de descubrimiento de bajo nivel. |
| 3 | 1+2 | Prototipo de regla de descubrimiento de bajo nivel. |
| 5 | 1+4 | Regla de descubrimiento de bajo nivel descubierta (convertida desde prototipo). |
| 7 | 1+2+4 | Prototipo de regla de descubrimiento de bajo nivel descubierta. |
Ejemplos
Comprobación de permisos de usuario
¿Tiene el usuario permiso para escribir en equipos cuyos nombres comienzan con "MySQL" o "Linux"?
{
"jsonrpc": "2.0",
"method": "host.get",
"params": {
"countOutput": true,
"search": {
"host": ["MySQL", "Linux"]
},
"editable": true,
"startSearch": true,
"searchByAny": true
},
"id": 1
}Respuesta:
Un resultado cero significa que no hay equipos con permisos de lectura/escritura.
Conteo de no coincidencias
Cuenta el número de equipos cuyos nombres no contienen la subcadena "ubuntu"
{
"jsonrpc": "2.0",
"method": "host.get",
"params": {
"countOutput": true,
"search": {
"host": "ubuntu"
},
"excludeSearch": true
},
"id": 1
}Respuesta:
Búsqueda de equipos usando comodines
Encuentra equipos cuyo nombre contenga la palabra "server" y tengan puertos de interfaz "10050" o "10071". Ordena el resultado por nombre de equipo en orden descendente y limítalo a 5 equipos.
{
"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 añade el parámetro "preservekeys" a la solicitud anterior, el resultado se devuelve como un array asociativo, donde las claves son el id de los objetos.
{
"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
}