[comment]: # ({6d056871-6d056871}) # Apéndice 1. Comentario de referencia [comment]: # ({/6d056871-6d056871}) [comment]: # ({6594bdc4-6594bdc4}) ### Notación [comment]: # ({/6594bdc4-6594bdc4}) [comment]: # ({8c926b1a-2df08058}) #### 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.| ::: noteimportant La API de Zabbix siempre devuelve valores solo como cadenas o arrays. ::: [comment]: # ({/8c926b1a-2df08058}) [comment]: # ({8f68b338-a2c16a18}) #### 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 `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; - ***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 `operationtype` se establece en "script global" y `opcommand_hst` no está establecido). ::: noteclassic 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. [comment]: # ({/8f68b338-a2c16a18}) [comment]: # ({f960f4be-f255da9d}) #### 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_mode` del 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. [comment]: # ({/f960f4be-f255da9d}) [comment]: # ({cf59def4-5e99748d}) ### 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"). [comment]: # ({/cf59def4-5e99748d}) [comment]: # ({da9957c2-b4e0f5ab}) ### Parámetros comunes de los métodos "get" Los siguientes parámetros son compatibles con todos los métodos `get`: |Parámetro|[Tipo](#data-types)|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 para 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](#data-types).

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](/manual/api/reference/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 entre mayúsculas y 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](#data-types).

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](/manual/api/reference/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`.| [comment]: # ({/da9957c2-b4e0f5ab}) [comment]: # ({1f52febe-4a0aeab6}) ### 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.| [comment]: # ({/1f52febe-4a0aeab6}) [comment]: # ({b41637d2-b41637d2}) ### Ejemplos [comment]: # ({/b41637d2-b41637d2}) [comment]: # ({7f8a25ac-7a121fac}) #### Comprobación de permisos de usuario ¿Tiene el usuario permiso para escribir en equipos cuyos nombres comienzan con "MySQL" o "Linux"? [Solicitud](/manual/api#performing-requests): ```json { "jsonrpc": "2.0", "method": "host.get", "params": { "countOutput": true, "search": { "host": ["MySQL", "Linux"] }, "editable": true, "startSearch": true, "searchByAny": true }, "id": 1 } ``` Respuesta: ```json { "jsonrpc": "2.0", "result": "0", "id": 1 } ``` ::: noteclassic Un resultado cero significa que no hay equipos con permisos de lectura/escritura. ::: [comment]: # ({/7f8a25ac-7a121fac}) [comment]: # ({b814e950-ea3cccd8}) #### Conteo de no coincidencias Cuenta el número de equipos cuyos nombres no contienen la subcadena "ubuntu" [Solicitud](/manual/api#performing-requests): ```json { "jsonrpc": "2.0", "method": "host.get", "params": { "countOutput": true, "search": { "host": "ubuntu" }, "excludeSearch": true }, "id": 1 } ``` Respuesta: ```json { "jsonrpc": "2.0", "result": "44", "id": 1 } ``` [comment]: # ({/b814e950-ea3cccd8}) [comment]: # ({a325f949-e911c08b}) #### 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. [Solicitud](/manual/api#performing-requests): ```json { "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: ```json { "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 } ``` [comment]: # ({/a325f949-e911c08b}) [comment]: # ({8c8fa5f6-8ce6f554}) #### 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. [Solicitud](/manual/api#performing-requests): ```json { "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: ```json { "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 } ``` [comment]: # ({/8c8fa5f6-8ce6f554})