1. Introducción
Con la API-REST de Checkmk como interfaz de programación de aplicaciones (API), puedes enviar tareas al servidor Checkmk mediante comandos o scripts con solicitudes HTTP y hacer que se ejecuten; tareas que, de otro modo, realizarías en Checkmk a través de la GUI.
El «REST» del nombre «API-REST» significa «REpresentational State Transfer» (transferencia de estado representacional) y describe una arquitectura para el intercambio de datos en sistemas distribuidos, especialmente para servicios web. Una API implementada según la arquitectura REST sigue ciertos principios, como el modelo cliente-servidor, la comunicación sin estado y una interfaz uniforme. En la práctica, la implementación se lleva a cabo preferiblemente a través del protocolo HTTP, en el que los recursos se direccionan mediante el Identificador Uniforme de Recursos (URI) y se accede a ellos utilizando métodos HTTP (GET, POST, PUT, DELETE).
Hasta aquí los principios de REST. Las ventajas de estos principios se pueden demostrar con las características concretas que ofrece la API-REST de Checkmk:
Protocolo |
Se utiliza el Protocolo de Transferencia de Hipertexto (HTTP/1.1) como sistema de transporte para la comunicación. |
Codificación |
Se utiliza la Notación de Objetos JavaScript (JSON) como formato de datos. La carga útil de las respuestas se serializa con JSON y se codifica en UTF-8. La información de fecha y hora se codifica en el formato ISO-8601 con información válida de zona horaria. |
Idioma |
El inglés es el idioma utilizado para las etiquetas, los identificadores y la documentación de la API. |
Autenticación |
Solo se concede acceso a la API a un cliente si ha demostrado su autorización mediante autenticación HTTP, por ejemplo, «Bearer». |
Versiones |
La API está versionada y utiliza un esquema de numeración conforme al estándar Semantic Versioning 2.x. Para más detalles, consulta la sección sobre versionado más abajo. |
Documentación |
La API está documentada en un formato legible por máquinas y en un formato legible por personas, en inglés, e incluye todos los recursos, sus parámetros de entrada y salida y sus rangos de valores asociados. La API se ha creado con la especificación OpenAPI (OAS) 3.x, un formato de descripción de la API pensado especialmente para las API-REST. El documento de la API creado con esta especificación se muestra al usuario con ReDoc, un diseño web adaptativo para documentos OpenAPI. |
Ejemplo de código |
Para mostrar cómo se usa, se proporciona código ejemplo para varias aplicaciones en cada solicitud, como curl y httpie. |
Visualización de errores |
En caso de error, la API envía códigos de estado HTTP numéricos y un mensaje de diagnóstico del problema, lo que ayuda a identificar posibles causas de solicitudes incorrectas. |
Clasificación de la API-REST |
La API cumple los cuatro niveles (del 0 al 3) del Modelo de Madurez de Richardson (RMM), que se puede usar para evaluar el grado de REST que contiene una API. El nivel 1 requiere la introducción de recursos para permitir la comunicación a través de la API con endpoints individuales en lugar de con uno global. El nivel 2 se cumple si se usan métodos HTTP para las solicitudes. En el nivel 3 (el más alto), la API es, en la práctica, autodocumentada, ya que el servidor, al responder a una solicitud, comunica las posibles acciones siguientes y los recursos a los que hay que dirigirse, lo que permite al cliente descubrir por sí mismo la funcionalidad disponible. Esta provisión de información adicional también se conoce como «Hypermedia as the Engine of Application State» (HATEOAS). |
Además de estas funciones generales de comodidad, la API-REST está pensada para cubrir toda la funcionalidad que en versiones anteriores de Checkmk se ofrecía a través de la GUI y una interfaz de comandos.
En el caso de las funciones que solo existen en las ediciones comerciales, como el service level agreement (SLA) o Agent bakery, los métodos de la API-REST asociados también se proporcionan únicamente en estas ediciones.
 |
This is a machine translation based on the English version of the article. It might or might not have already been subject to text preparation. If you find errors, please file a GitHub issue that states the paragraph that has to be improved. |
2. La documentación de la API
2.1. Versiones
Una de las ventajas de la API-REST es que tanto el software como su documentación provienen de la misma fuente: el documento OpenAPI. Por lo tanto, la documentación de la API siempre coincide con el software y describe exactamente lo que la API puede hacer. Por eso no es necesario describir la parte de referencia de los recursos, métodos, parámetros, etc. disponibles en el Manual de usuario de Checkmk; en su lugar, encontrarás la documentación de la API por separado de este manual, directamente en tu sitio de Checkmk.
La API y su documentación están versionadas y utilizan un esquema de numeración de dos niveles con el formato X.Y, donde X representa una versión principal y Y una versión secundaria.
Una nueva versión secundaria solo contiene cambios compatibles con versiones anteriores que no afectan a las funciones existentes.
Una nueva versión principal, por otro lado, contiene cambios que hacen que la API sea incompatible con la versión principal anterior (los llamados «cambios rompedores»).
Los números de versión de las versiones principales y secundarias forman parte de la URL con la que se envía una solicitud al servidor.
La API-REST de Checkmk no utiliza actualmente el tercer nivel (.Z) del estándar de versionado semántico para una versión de parche.
Ten en cuenta que la API-REST sigue un esquema de versionado diferente al del software Checkmk. Dado que se necesita una nueva versión principal de la API-REST si hay cambios incompatibles en la API-REST, esto no suele tener una coincidencia con el ciclo de lanzamiento del software Checkmk.
No obstante, la correlación entre las versiones de la documentación de la API y el software Checkmk es muy sencilla, como verás en el siguiente capítulo.
2.2. Acceso
La documentación de la API-REST está disponible en formato HTML para consultarla en un navegador web.
En la GUI de Checkmk, abre la documentación de la API desde la barra de navegación a través de Help > Developer resources > REST API documentation. La documentación de la API se muestra en una nueva ventana (o pestaña) del navegador. Hablaremos de esto con más detalle en el siguiente capítulo.
 |
Seguramente habrás notado que hay más entradas relacionadas con la API-REST en el menú Help. Con REST API introduction puedes abrir este artículo. Con REST API interactive GUI puedes abrir otra vista de la API-REST. La entrada se llama GUI, ya que no solo se te muestran las funciones de la API-REST, sino que también puedes interactuar con la API-REST directamente desde el navegador, por ejemplo, enviando solicitudes al servidor. Presentaremos la GUI de la API-REST como alternativa a la ejecución mediante script más adelante, en el capítulo dedicado a la GUI de la API-REST. |
2.3. Estructura y contenido
La documentación de la API utiliza un diseño web adaptativo que consta de tres secciones:
La sección de la izquierda, Navegación, sirve para orientarte, buscar y saltar rápidamente a la descripción exacta de las entradas de la sección central. El índice contiene una entrada para cada endpoint de la API. Un endpoint utiliza una URL para hacer referencia al recurso que proporciona la API (por ejemplo, hosts), junto con el método utilizado para acceder al recurso (por ejemplo, GET para mostrar un host). Los endpoints están organizados en varias carpetas.
La sección central, «Contenido», contiene los datos concretos de la documentación: toda la información para definir una solicitud (con parámetros, rangos de valores, valores por defecto y descripciones) y las respuestas correspondientes (también con todos los detalles). Las posibles respuestas se muestran en diferentes colores, dependiendo de si el código de estado HTTP devuelto indica éxito o un error.
La sección de la derecha, «Request samples», muestra el método y la URL del endpoint seleccionado en la sección de contenido, seguido de varios ejemplos de solicitudes: la carga útil en formato JSON (si es relevante para el endpoint) y ejemplos de código, p. ej., para curl, httpie, Python Requests y Python Urllib. A continuación, aparecen las respuestas según el código de estado HTTP. Todos los ejemplos de código se pueden copiar al portapapeles con el botón «Copy».
La sección de navegación está sincronizada con el desplazamiento de las otras dos secciones, lo que significa que si te desplazas hacia arriba o hacia abajo en la sección de contenido, la sección de navegación se desplaza automáticamente hasta la entrada correspondiente en el índice.
El diseño web adaptativo garantiza que la sección de ejemplos no se vea en una ventana del navegador web muy estrecha (los ejemplos se muestran entonces debajo del método correspondiente), y la sección de navegación se convierte en un menú.
En todas las secciones encontrarás contenido que puedes mostrar y ocultar, por ejemplo, las entradas de los endpoints en la sección de navegación y los parámetros anidados en la sección de contenido. Al hacer clic en > o Expand all puedes mostrar el contenido oculto, y con ∨ o Collapse all puedes volver a ocultarlo.
En el siguiente capítulo aprenderás cómo puedes utilizar la documentación de la API para crear solicitudes concretas a partir de la información, enviar estas solicitudes al servidor Checkmk, hacer que se ejecuten y supervisar dicha ejecución y los resultados.
3. Uso de la API
3.1. Autenticación
Para poder usar la API-REST del servidor Checkmk desde un cliente, este debe demostrar su identidad. La API-REST admite los siguientes métodos de autenticación: Bearer, servidor web y cookie, en este orden de prioridad. Esto significa, por ejemplo, que si la autenticación con Bearer se realiza correctamente, no se comprobarán los demás métodos.
Autenticación Bearer o Header
«Bearer» significa el portador de una identidad. El cliente se autentica con las credenciales de un usuario configurado en el servidor Checkmk. Lo ideal es que se trate del llamado usuario de automatización, que Checkmk proporciona para la ejecución de acciones a través de una API. Se recomienda utilizar la autenticación Bearer en scripts.
Para la autenticación, necesitas el nombre de usuario y el llamado «secreto de automatización» correspondiente para las cuentas de máquina, es decir, la contraseña del usuario de automatización. Ambos datos deben transmitirse al servidor Checkmk en el encabezado de cada solicitud.
Puedes encontrar los usuarios de automatización, al igual que otros usuarios, en Setup > Users > Users. Asegúrate de que los roles y los permisos asociados al usuario de automatización estén configurados para permitirte ejecutar tus solicitudes.
Para los scripts que se presentan en este artículo, siempre se utiliza como ejemplo un usuario de automatización llamado automation.
Autenticación del servidor web
Para la autenticación del servidor web, la API-REST utiliza la autenticación HTTP configurada para el servidor web («Basic» o «Digest»).
Este método de autenticación está pensado para instalaciones grandes de Checkmk con requisitos especiales que se implementan mediante el uso y la configuración de módulos de software para la autenticación del servidor web Apache. Si quieres usar la autenticación del servidor web, tienes que reconfigurar el servidor web Apache del propio site de Checkmk.
Autenticación por cookie
La autenticación por cookie es un caso especial de autenticación mediante clave API. Cualquier usuario de Checkmk que haya iniciado sesión en Checkmk y al que se le haya asignado una cookie HTTP puede utilizar la API-REST. La autenticación por cookie se utiliza para probar y realizar pruebas con la GUI de la API-REST. La ejecución de las solicitudes depende de si tu cuenta de usuario de Checkmk tiene los permisos adecuados.
3.2. Código de estado HTTP
La API-REST devuelve el código de estado HTTP para cada solicitud, que puedes utilizar para checkear si la solicitud se ha realizado correctamente. La lista de los códigos de estado HTTP posibles para la solicitud se encuentra en la documentación de la API-REST.
Ten en cuenta que el código de estado HTTP solo proporciona información sobre si la transmisión de la solicitud se ha realizado correctamente, pero no sobre si la ejecución ha tenido éxito. Los comandos se ejecutan en el servidor Checkmk con Livestatus. Para asegurarte de que la solicitud a través de la API-REST realmente hace lo que tú pretendías, debes verificar el éxito por ti mismo. La documentación de la API, que puedes abrir en Help > Developer resources > REST API interactive GUI, contiene un ejemplo de script para esta tarea en la sección «Consultas a través de la API-REST».
3.3. Probar la API localmente
Para probar la API-REST, es recomendable realizar las solicitudes directamente desde el servidor Checkmk, es decir, en este ejemplo, el cliente que envía la solicitud y el servidor que la recibe se encuentran en el mismo ordenador.
Si estás trabajando como usuario del site, también puedes utilizar variables locales como $OMD_SITE, que hace referencia al nombre del site.
En los siguientes ejemplos sencillos, utilizamos el código ejemplo incluido en la documentación de la API para el programa de línea de comandos curl, que permite transferir datos hacia o desde un servidor sin interacción del usuario, por ejemplo, a través de HTTP.
|
Especialmente en el caso de solicitudes complejas, los ejemplos de curl pueden contener inconsistencias y, por lo tanto, puede que no siempre sean fiables. Con httpie hay una alternativa disponible que es consistente, fácil de entender y muy adecuada para su uso en scripts. |
El comando `curl` se ejecuta dentro de un script de bash.
Para prepararlo, crea un archivo de script para cada una de las solicitudes que se ejecutarán en la siguiente sección, en el que luego se copiará el código ejemplo:
La API-REST devuelve todas las respuestas en formato JSON de una sola línea.
Dado que la salida formateada facilita mucho la lectura, los siguientes ejemplos muestran la salida de una sola línea formateada en varias líneas.
Existen varios sitios web y herramientas para procesar el formato JSON, por ejemplo, el procesador de JSON de línea de comandos jq.
Antes de empezar, recopila información básica específica de tu configuración de Checkmk:
| Variable | Valor de ejemplo | Significado |
|---|---|---|
|
|
El nombre de host del servidor Checkmk |
|
|
El nombre del site de Checkmk |
|
|
El nombre del usuario de automatización |
|
|
La contraseña del usuario de automatización |
Estas variables se usan en el código ejemplo y debes editarlas antes de enviar una solicitud. En la tabla anterior también encontrarás los valores de ejemplo que se usan a continuación.
3.4. Realizar solicitudes mediante scripts
Con un ejemplo sencillo, te mostraremos ahora cómo utilizar la API-REST. Crea un host con sus servicios utilizando un total de cuatro solicitudes. En principio, debes proceder de la misma manera que lo harías con la GUI de Checkmk:
Crea un host
Realiza el descubrimiento de servicios en el host
Mostrar cambios pendientes
Activar los cambios
Crear un host
Abre la documentación de la API y selecciona la entrada para crear un host (Create a host) en el área de navegación de la izquierda:
En la parte central del panel puedes ver los detalles de la solicitud seleccionada, qué autenticación HTTP se requiere (es la misma para todas las solicitudes a través de la API-REST) y los parámetros obligatorios y opcionales. Es obligatorio indicar el nombre del host y la carpeta en la que debe crearse. Por defecto, el host se crea en la carpeta Main. Si quieres crear el host en otra carpeta, es posible que primero tengas que realizar otra solicitud de API (Show all folders) para ver las carpetas existentes y determinar el ID de la que quieres usar.
En nuestro ejemplo, el host myhost123 se creará con la dirección IP 192.168.0.42 en la carpeta Main.
En la documentación de la API, haz clic en el botón curl en el área de ejemplo de la derecha y, a continuación, haz clic en Copy para copiar el código ejemplo de curl al portapapeles.
Abre el script preparado create_host.sh y pega el contenido del portapapeles en él:
En la primera parte del código ejemplo encontrarás las variables del entorno, luego viene el comando curl con el método POST en el recurso cuya URL se encuentra en la última línea.
La opción -write-out finalmente muestra una línea con el código de estado HTTP.
Las líneas de encabezado (una de las cuales define la autenticación HTTP) van seguidas de la sección de datos en la que se definen los parámetros para el nuevo host.
Ten en cuenta que el código ejemplo de curl puede contener más parámetros de los que necesitas para una situación concreta.
En nuestro ejemplo no es así, y solo tienes que cambiar los dos parámetros existentes: host_name y ipaddress.
Ahora edita el código ejemplo para que el resultado sea algo así:
Ejecuta el script:
Recordatorio: La única línea en formato JSON delimitada por llaves se muestra aquí en varias líneas.
La API devuelve en links una selección de solicitudes (abreviadas en nuestro ejemplo anterior), que se pueden aplicar al host que acabas de crear, como corresponde a una API-REST.
Por último, la API devuelve el ID y el nombre (title) del host creado, el nombre de folder (/ para la Carpeta principal) y el attributes asignado al host, incluida la dirección IP.
Por último, se muestra la línea con el código de estado HTTP.
El 200 significa OK y indica que la acción se ha realizado correctamente.
Realiza un descubrimiento de servicios en el host
Una vez creado el myhost123 del host, se pueden detectar sus servicios.
Para garantizar que el descubrimiento de servicios realmente proporcione los servicios esperados, en los hosts Linux y Windows debes instalar y registrar primero sus respectivos agentes.
Para ejecutar el descubrimiento de servicios a través de la API-REST, selecciona la entrada correspondiente en la documentación de la API (Execute a service discovery on a host), copia el código ejemplo en el archivo de script creado para este fin y adáptalo.
Puedes copiar la primera parte con las variables del entorno tal cual del ejemplo anterior.
En el comando curl, cambia el nombre del host por myhost123 y, si es necesario, utiliza el parámetro mode para cambiar el tipo de descubrimiento de servicios.
Ejecuta también este script:
En este caso, el código de estado HTTP 303 significa que se ha iniciado el trabajo en segundo plano para el descubrimiento de servicios.
Mostrar cambios pendientes
Antes de activar los cambios, es necesario un paso intermedio: mostrar los cambios pendientes con la solicitud Show all pending changes. Además de los cambios que se han acumulado, la API-REST también proporciona el ETag HTTP (tag de entidad) que necesitas para activar estos cambios. Un objeto no se modifica a través de la API-REST utilizando el ID o el título del objeto. En su lugar, se utiliza el ETag generado para evitar que múltiples solicitudes simultáneas sobrescriban los valores del mismo objeto.
El ETag se devuelve en el encabezado de la respuesta.
Para mostrar este encabezado, amplía el código de ejemplo de esta solicitud llamando a curl con la opción -i (para incluir los encabezados de respuesta).
Las líneas modificadas también se marcan de nuevo en el siguiente ejemplo:
Una vez ejecutado el script, las líneas del encabezado se muestran primero en la salida:
Para mayor claridad, aquí se ha acortado la salida y solo se han marcado las líneas importantes: la línea de encabezado con el ETag, los atributos del único cambio pendiente para crear un host y el código de estado HTTP de OK.
Necesitarás el ETag en el siguiente y último paso.
Activa los cambios
Por último, hay que activar los cambios. La solicitud correspondiente se llama Activate pending changes.
En el comando curl, cambia la línea de encabezado If-Match e inserta el ETag que has leído en la sección anterior.
En la sección de datos, cambia el parámetro sites y configúralo con el nombre del site en el que se deben activar los cambios:
Ejecuta este script:
El texto «title» indica que se ha iniciado la activación.
Una vez más, la API-REST sugiere dos solicitudes de seguimiento útiles en «links»:
para consultar el estado de esta activación y para esperar a que se complete.
3.5. Realizar solicitudes a través de la GUI de la API-REST
Con la GUI de la API-REST obtienes una nueva perspectiva de la API. Con esta GUI puedes interactuar directamente con la API desde el navegador enviando solicitudes al servidor mediante comandos curl y ver las respuestas de inmediato. Para ello, debes prescindir de los ejemplos de código de la documentación de la API-REST en la GUI de la API-REST: ambas vistas están optimizadas para sus respectivas funciones.
La GUI de la API-REST se genera a partir de la misma fuente que la documentación de la API-REST —el documento OpenAPI— y, por lo tanto, siempre ofrece funciones que coinciden con la API.
Puedes abrir la GUI de la API en la GUI de Checkmk desde la barra de navegación, en el menú «Help > Developer resources > REST API interactive GUI». La GUI de la API se muestra en una nueva ventana del navegador (o pestaña del navegador):
A continuación te explicamos cómo puedes ejecutar la primera solicitud del ejemplo anterior (crear un host) con la GUI de la API-REST en lugar de usar un script:
Autentificación: La GUI de la API-REST ofrece un cuadro de diálogo para introducir la información de autenticación tras hacer clic en el botón «Authorize» (a la derecha, encima de la entrada de la primera carpeta de endpoints). Sin embargo, si has iniciado sesión como usuario del site, no necesitas introducir nada ahí, ya que estás autorizado a usar la API-REST como usuario de Checkmk mediante la autenticación por cookie.
Selecciona el endpoint: En la carpeta «Hosts», selecciona el endpoint «Create a host» y haz clic en «Try it out».
Introduce los valores de los parámetros: En Request body, sobrescribe los valores de ejemplo de
host_nameyipaddress.Envía una solicitud: Haz clic en «Execute».
Comprueba la respuesta: En Responses verás primero el comando curl enviado y la URL del endpoint. A continuación, en Server response se muestra la respuesta con el código de estado HTTP y en Responses con la respuesta de la API-REST (formateada en varias líneas).
Por lo tanto, la GUI de la API-REST te ofrece la oportunidad de probar las funciones de la API de forma rápida y sencilla, y de familiarizarte con las funciones de los valores de entrada, así como con las respuestas concretas.
3.6. Corrección de errores
A diferencia de la salida de los comandos ejecutados con éxito mediante script que se ha mostrado hasta ahora, la API-REST te muestra los errores de la siguiente manera:
{
"title": "The operation has failed.",
"status": 401,
"detail": "There are changes from other users and foreign changes are not allowed in this API call."
}
xxx-status_code=401Dependiendo del error, los parámetros que se muestran en la salida pueden variar.
Sin embargo, en status siempre aparece el código de estado HTTP, y en title siempre se incluye una breve descripción de la causa del error.
En la mayoría de los casos, detail te mostrará información detallada, como su nombre indica.
En el ejemplo anterior, puedes ver que hay cambios pendientes en Checkmk, pero estos fueron iniciados por otro usuario.
Por defecto, solo los cambios que también se hayan realizado a través de la API pueden activarse mediante la API.
En el siguiente ejemplo, los mensajes de ayuda también se encuentran en la información detallada:
{
"title":"Bad Request",
"status":400,
"detail":"These fields have problems: host_name",
"fields":{
"host_name":[
"'my/host123' does not match pattern '^[-0-9a-zA-Z_.]+\\\\Z'."
]
}
}
xxx-status_code=400El problema en el ejemplo anterior es que el valor de un parámetro no se ajusta al rango de valores válido porque el nombre del host contiene una barra.
El número de posibles errores es, por supuesto, mucho mayor que los dos que hemos presentado aquí. Sin embargo, como puedes ver en los ejemplos mostrados, en su salida la API-REST suele proporcionar información suficiente sobre la causa y, por lo tanto, te da pistas para iniciar el análisis y la resolución de problemas.
4. Proteger la API
Dado que durante el acceso a través de la API-REST se pueden transferir datos confidenciales y —dependiendo de la autorización del usuario de automatización— se podrían realizar modificaciones considerables en Checkmk, debes proteger dicho acceso adecuadamente. Aquí encontrarás algunas de las opciones disponibles:
Checkmk a través de HTTPS: Utiliza la API exclusivamente a través del Protocolo Seguro de Transferencia de Hipertexto (HTTPS); de lo contrario, los nombres de usuario, las contraseñas y también los datos de configuración se transmitirán en texto sin cifrar por la red.
Asigna al usuario de automatización una contraseña de longitud suficiente. Dado que la contraseña suele almacenarse únicamente en un script, puedes asignar fácilmente una muy larga.
Presta especial atención al concepto de autorización de los scripts que utilices para realizar solicitudes a la API. Los scripts pueden contener datos confidenciales, como datos de configuración, contraseñas, etc. Por lo tanto, asegúrate de que solo los usuarios y grupos autorizados puedan leer estos scripts.
5. Ejemplos con solicitudes de la API-REST
En este capítulo encontrarás ejemplos que muestran cómo realizar acciones habituales mediante la API-REST.
Los ejemplos se basan, de nuevo, en el código ejemplo del programa de línea de comandos curl.
Sin embargo, a diferencia del procedimiento descrito en el capítulo «Uso de la API-REST», aquí las solicitudes se realizan como comandos de lcurle en la línea de comandos, en lugar de mediante un script.
Esto te permite probar nuestros ejemplos de inmediato, una vez que los hayas adaptado a tu propio entorno.
Para presentar los comandos de forma clara, solo hemos mostrado las líneas del código ejemplo que son absolutamente necesarias para la ejecución del comando.
Al igual que con el código ejemplo de la documentación de la API-REST, los ejemplos de este capítulo contienen variables para armar la URL base de la API-REST en tu servidor Checkmk y para configurar las credenciales del usuario de automatización para la autenticación Bearer utilizada:
| Variable | Valor de ejemplo | Descripción |
|---|---|---|
|
|
Nombre del servidor Checkmk |
|
|
Nombre del site de Checkmk |
|
|
URL base de l'API-REST |
|
|
Nombre del usuario de automatización |
|
|
Contraseña del usuario de automatización |
Antes de ejecutar los comandos curl, puedes adaptar las variables a tu entorno utilizando los siguientes comandos de shell:
5.1. Hosts y carpetas
Las solicitudes descritas en este capítulo se pueden encontrar en la documentación de la API, en las subcarpetas Hosts y Folders. Los títulos de los respectivos endpoints que figuran en la documentación de la API son los siguientes encabezados.
Mostrar todas las carpetas
Aquí se muestran todas las carpetas de la configuración —de forma recursiva a partir de la carpeta Main— sin crear una lista de los hosts que contienen:
Mostrar todos los hosts de una carpeta
Aquí se solicitan los hosts de la subcarpeta «Main > Linux»:
Crear una carpeta
Aquí se crea una subcarpeta «Production Hosts» en «Main > Linux» —en el sistema de archivos como el directorio «production_hosts».
De este modo, a la nueva carpeta se le asigna el tag del host «Productive system» del grupo de tags de host predefinido «Criticality»:
Crear un host
Aquí, en la carpeta Main > Linux > Production Hosts, se crea el host mylinuxserver con la dirección IP 192.168.0.123 y el tag del host Use piggyback data from other hosts if present:
Mostrar un host
Al mostrar un host, obtienes una lista de los atributos que se le han asignado. Esto te proporciona además el ETag HTTP (etiqueta de entidad) que necesitas para poder modificar un host. Puedes obtener más información sobre el ETag en la sección «Mostrar cambios pendientes».
El ETag se devuelve en el encabezado de la respuesta.
Para mostrar este encabezado, llama a curl con la opción -v (para obtener información detallada).
Aquí se consulta el host mylinuxserver, y de la respuesta solo se muestra la línea que contiene el ETag:
Actualizar un host
Antes de realizar el cambio, obtén el ETag de ese host tal y como se describe en la sección anterior Mostrar un host.
A continuación, introduce el ETag en el encabezado de la solicitud en If-Match.
Aquí se elimina el tag del host del grupo Piggyback que se especificó al crear el host, y se especifica el tag predefinido API integrations if configured, else Checkmk agent para sustituirlo:
Ejecutar un descubrimiento de servicios en un host
Para asegurarte de que el descubrimiento de servicios realmente ofrece los servicios esperados, en los hosts Linux y Windows primero debes instalar y registrar sus respectivos agentes de monitorización.
Aquí se realiza el descubrimiento de servicios en el host mylinuxserver con la opción tabula_rasa, que corresponde al botón Remove all and find new en la GUI de Checkmk:
Crear hosts de manera masiva
Aquí se crean dos hosts en la carpeta Main > Linux > Production Hosts: el primer host solo con una dirección IP, y el segundo host con un host padre y dos etiquetas además de su dirección IP:
Activar cambios pendientes
Antes de poder abordar la compleja acción de renombrar un host, es necesario activar todos los cambios que se han acumulado en su entorno de configuración.
Aquí se activan todos los cambios para el site mysite en una sola acción:
Renombrar un host
Un nuevo nombre también cambiará el host.
Por lo tanto, primero obtén el ETag actual del host, por ejemplo, de mylinuxserver, tal y como se describe en la sección «Mostrar un host», e introdúcelo en el encabezado de la solicitud en «If-Match».
Aquí se está renombrando el host como mylinuxserver01: