1. Introduction
Grâce à l'API REST de Checkmk, vous pouvez transmettre des tâches au serveur Checkmk par instruction ou script à l'aide de requêtes HTTP et les faire exécuter — des tâches que vous effectueriez autrement dans Checkmk via l'interface graphique.
Le sigle REST dans le nom de l’API REST signifie REpresentational State Transfer (transfert d’état représentatif) et décrit une architecture pour l’échange de données sur des systèmes distribués — en particulier pour les services web. Une API mise en œuvre selon l’architecture REST suit certains principes, par exemple le modèle client-serveur, la communication sans état et une interface uniforme. En pratique, la mise en œuvre s’effectue de préférence via le protocole HTTP, les ressources étant adressées via l’Uniform Resource Identifier (URI) et accessibles à l’aide de méthodes HTTP (GET, POST, PUT, DELETE).
Voilà pour les principes de REST. Les avantages de ces principes peuvent être illustrés par les fonctionnalités concrètes offertes par l’API REST de Checkmk :
Protocole |
Le protocole HTTP (HTTP/1.1) est utilisé comme système de transport pour la communication. |
Codage |
Le format JSON (JavaScript Object Notation) est utilisé comme format de données. La charge utile des réponses est sérialisée au format JSON et encodée en UTF-8. Les informations de date et d'heure sont encodées au format ISO-8601 avec des informations de fuseau horaire valides. |
Langage |
L'anglais est la langue utilisée pour les étiquettes, les identifiants et la documentation de l'API. |
Authentification |
L'accès à l'API n'est accordé à un client que s'il a prouvé son autorisation au moyen d'une authentification HTTP — « Bearer » par exemple. |
Version |
L'API est versionnée et utilise un schéma de numérotation conforme à la norme Semantic Versioning 2.x. Pour plus de détails, veuillez vous reporter à la section sur la gestion des versions ci-dessous. |
Documentation |
L'API est documentée dans une structure lisible par machine, ainsi que dans un format lisible par l'utilisateur, en anglais, et comprend toutes les ressources, leurs paramètres d'entrée et de sortie, ainsi que leurs plages de valeurs associées. L'API est créée à l'aide de la spécification OpenAPI (OAS) 3.x, un format de description de l'API spécialement conçu pour les API REST. Le document API créé à l'aide de cette spécification est présenté à l'utilisateur via ReDoc, une interface web adaptative pour les documents OpenAPI. |
Exemple de code |
Afin d’illustrer son utilisation, des exemples de code pour diverses applications sont fournis pour chaque requête — curl et httpie, par exemple. |
Affichage des erreurs |
En cas d’erreur, l’API renvoie des codes HTTP numériques ainsi qu’un message de diagnostic du problème, ce qui permet d’identifier les causes possibles des requêtes incorrectes. |
Classification des API REST |
L'API répond aux quatre niveaux (0 à 3) du modèle de maturité de Richardson (RMM), qui permet d'évaluer le degré de conformité REST d'une API. Le niveau 1 nécessite l'introduction de ressources permettant la communication via l'API vers des ressources individuelles plutôt que vers une ressource globale. Le niveau 2 est atteint si des méthodes HTTP sont utilisées pour les requêtes. Au niveau 3 (le plus élevé), l’API est en fait auto-documentée, en ce sens que le serveur, lorsqu’il répond à une requête, communique toutes les actions suivantes possibles et les ressources à adresser, permettant ainsi au client de découvrir par lui-même les fonctionnalités disponibles. Cette fourniture d’informations supplémentaires est également connue sous le nom de « Hypermedia as the Engine of Application State » (HATEOAS). |
Outre ces fonctions de confort générales, l’API REST est destinée à couvrir l’ensemble des fonctionnalités qui, dans les versions antérieures de Checkmk, étaient fournies via l’interface graphique et une interface de commande.
Pour les fonctionnalités qui n’existent que dans les éditions commerciales, telles que le service level agreement (SLA) ou la boulangerie d’agents, les méthodes API REST associées ne sont également fournies que dans ces éditions.
 |
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 documentation de l'API
2.1. Gestion des versions
L'un des avantages de l'API REST réside dans le fait que le logiciel et sa documentation proviennent de la même source : le document OpenAPI. Ainsi, la documentation de l'API correspond toujours au logiciel et décrit exactement ce que l'API est capable de faire. Il n'est donc pas nécessaire de décrire la partie de référence des ressources, méthodes, paramètres, etc. disponibles dans le guide de l'utilisateur Checkmk ; vous trouverez plutôt la documentation de l'API séparément de ce manuel, directement sur votre site Checkmk.
L’API et sa documentation sont versionnées et utilisent un schéma de numérotation à deux niveaux au format X.Y, où X correspond à une version majeure et Y à une version mineure.
Une nouvelle version mineure ne contient que des modifications rétrocompatibles qui n’ont aucun effet sur les fonctions existantes.
Une nouvelle version majeure, en revanche, contient des modifications qui rendent l’API incompatible avec la version majeure précédente (ce que l’on appelle des modifications de rupture).
Les numéros de version des versions majeures et mineures font partie de l’URL avec laquelle une requête est envoyée au serveur.
L’API REST Checkmk n’utilise actuellement pas le troisième niveau (.Z) de la norme de versionnement sémantique pour une version de correctif.
Notez que l’API REST suit un schéma de versionnement différent de celui du logiciel Checkmk. Étant donné qu’une nouvelle version majeure de l’API est nécessaire en cas de modifications incompatibles de l’API, celle-ci ne correspond généralement pas au cycle de publication du logiciel Checkmk.
Néanmoins, la corrélation entre les versions de la documentation de l'API et celles du logiciel Checkmk est très simple, comme vous le verrez dans le chapitre suivant.
2.2. Accès
La documentation de l'API REST est disponible au format HTML pour être consultée dans un navigateur.
Dans l’interface graphique de Checkmk, ouvrez la documentation de l’API à partir de la barre de navigation via Help > Developer resources > REST API documentation. La documentation de l’API s’affiche dans une nouvelle fenêtre (ou un nouvel onglet) du navigateur. Nous aborderons ce point plus en détail dans le chapitre suivant.
 |
Vous avez certainement remarqué qu’il existe d’autres entrées concernant l’API REST dans le menu Help. Avec REST API introduction, vous pouvez ouvrir cet article. Avec REST API interactive GUI, vous pouvez ouvrir une autre vue de l’API REST. Cette entrée s’appelle « GUI » (Interface graphique de l’API REST) car non seulement les fonctions de l’API REST vous sont présentées, mais vous pouvez également interagir avec l’API directement depuis le navigateur — en envoyant des requêtes au serveur, par exemple. Nous présenterons l’interface graphique de l’API REST comme alternative à l’exécution par script plus loin dans le chapitre consacré à l’interface graphique de l’API REST. |
2.3. Structure et contenu
La documentation de l'API utilise une conception web adaptative composée de trois sections :
La section de gauche, intitulée « Navigation », sert à l’orientation, à la recherche et à accéder rapidement à la description précise des entrées de la section centrale. La table des matières contient une entrée pour chaque ressource de l’API. Un point de terminaison utilise une URL pour faire référence à la ressource fournie par l’API (par exemple, les ordinateurs hôtes), ainsi que la méthode utilisée pour accéder à la ressource (par exemple, GET pour afficher un ordinateur hôte). Les points de terminaison sont organisés en plusieurs dossiers.
La section centrale, « Contenu », contient les informations concrètes de la documentation : toutes les informations nécessaires pour définir une requête (avec les paramètres, les plages de valeurs, les valeurs par défaut et les descriptions) ainsi que les réponses correspondantes (également avec tous les détails). Les réponses possibles sont affichées dans des couleurs différentes, selon que le code HTTP renvoyé indique une réussite ou une erreur.
La section de droite, «Request samples», affiche la méthode et l'URL de la ressource sélectionnée dans la section «Content», suivies de plusieurs exemples de requêtes : la charge utile au format JSON (si applicable à la ressource) et des exemples de code, par exemple pour curl, httpie, Python Requests et Python Urllib. Viennent ensuite les réponses en fonction du code HTTP. Tous les exemples de code peuvent être copiés dans le presse-papiers à l'aide du bouton «Copy».
La section de navigation est synchronisée avec les deux autres sections lors du défilement, ce qui signifie que si vous faites défiler la section de contenu vers le haut ou vers le bas, la section de navigation se déplace automatiquement vers l'entrée correspondante dans la table des matières.
La conception web adaptative garantit que la section des exemples n'apparaît pas dans une fenêtre de navigateur très étroite (les exemples sont alors affichés sous la méthode correspondante), et la section de navigation est convertie en menu.
Dans toutes les sections, vous trouverez du contenu que vous pouvez afficher et masquer, par exemple les entrées pour les ressources dans la section de navigation, et les paramètres imbriqués dans la section de contenu. En cliquant sur > ou Expand all, vous pouvez afficher le contenu masqué, et avec ∨ ou Collapse all, vous pouvez le masquer à nouveau.
Dans le chapitre suivant, vous apprendrez comment utiliser la documentation de l'API pour créer des requêtes concrètes à partir des informations, envoyer ces requêtes au serveur Checkmk, les faire exécuter et surveiller cette exécution ainsi que les résultats.
3. Utilisation de l'API
3.1. Authentification
Pour pouvoir utiliser l'API REST du serveur Checkmk depuis un client, ce dernier doit prouver son identité. L'API REST prend en charge les méthodes d'authentification suivantes : Bearer, serveur web et Cookie — dans cet ordre de priorité. Cela signifie, par exemple, que si l'authentification avec Bearer aboutit, aucune des autres méthodes ne sera vérifiée.
Authentification Bearer ou Header
« Bearer » désigne le détenteur d’une identité. Le client s’authentifie à l’aide des identifiants d’un utilisateur configuré sur le serveur Checkmk. Idéalement, il s’agit de l’utilisateur de l’automatisation, qui est fourni dans Checkmk pour l’exécution d’actions via une API. L’authentification Bearer est recommandée pour une utilisation dans des scripts.
Pour l’authentification, vous avez besoin du nom d’utilisateur et du mot de passe d’automatisation correspondant pour les comptes machine, c’est-à-dire le mot de passe de l’utilisateur de l’automatisation. Ces deux éléments d’information doivent être transmis au serveur Checkmk dans l’en-tête de chaque requête.
Vous trouverez les utilisateurs de l'automatisation, comme les autres utilisateurs, sous Setup > Users > Users. Assurez-vous que les rôles et les autorisations associées à l'utilisateur de l'automatisation sont configurés de manière à vous permettre d'exécuter vos requêtes.
Pour les scripts présentés dans cet article, un utilisateur de l'automatisation nommé automation est toujours utilisé à titre d'exemple.
Authentification du serveur web
Pour l'authentification du serveur web, l'API REST utilise l'authentification HTTP configurée pour le serveur web (« Basic » ou « Digest »).
Cette méthode d'authentification est destinée aux installations Checkmk de grande envergure présentant des exigences particulières, qui sont satisfaites par l'utilisation et la configuration de modules logiciels pour l'authentification du serveur web Apache. Si vous souhaitez utiliser l'authentification par le serveur web, vous devez reconfigurer le serveur web Apache de l'instance Checkmk elle-même.
Authentification par cookie
L'authentification par cookie est un cas particulier de l'authentification par clé API. Tout utilisateur Checkmk connecté à Checkmk et auquel un cookie HTTP a été attribué peut utiliser l'API REST. L'authentification par cookie est utilisée pour essayer et tester l'API REST via l'interface graphique. La possibilité d'exécuter des requêtes dépend des autorisations dont dispose votre compte utilisateur Checkmk.
3.2. Code HTTP
L'API REST renvoie le code HTTP pour chaque requête, ce qui vous permet de vérifier si la requête a abouti. La liste des codes HTTP possibles pour la requête est répertoriée dans la documentation de l'API.
Notez que le code HTTP fournit uniquement des informations sur la transmission réussie de la requête, mais pas sur son exécution réussie. Les instructions sont exécutées sur le serveur Checkmk avec Livestatus. Pour vous assurer que la requête via l'API REST produit bien le résultat escompté, vous devez vérifier vous-même sa réussite. La documentation de l'API, que vous pouvez ouvrir à l'adresse Help > Developer resources > REST API interactive GUI, contient un exemple de script pour cette tâche dans la section « Requêtes via l'API REST ».
3.3. Tester l'API en local
Pour tester l’API REST, il est conseillé d’effectuer les requêtes directement depuis le serveur Checkmk, c’est-à-dire que, dans cet exemple, le client envoyant la requête et le serveur la recevant se trouvent sur le même ordinateur.
Si vous travaillez en tant qu’utilisateur de l’instance, vous pouvez également utiliser des variables locales telles que $OMD_SITE, qui fait référence au nom de l’instance.
Dans les exemples simples suivants, nous utilisons l'exemple de code figurant dans la documentation de l'API pour le programme en ligne de commande curl, qui permet de transférer des données vers ou depuis un serveur sans interaction de l'utilisateur, par exemple via HTTP.
|
En particulier pour les requêtes complexes, les exemples curl peuvent présenter des incohérences et ne sont donc pas toujours fiables. Avec httpie, une alternative cohérente, facile à comprendre et bien adaptée à une utilisation dans des scripts est disponible. |
L’instruction curl est exécutée au sein d’un script bash.
Pour la préparation, créez un fichier de script pour chacune des requêtes à exécuter dans la section suivante, dans lequel l’exemple de code sera copié ultérieurement :
L'API REST renvoie toutes les réponses au format JSON sur une seule ligne.
Comme une sortie formatée facilite grandement la lecture, les exemples suivants présentent la sortie sur une seule ligne formatée sur plusieurs lignes.
Il existe divers sites web et outils pour traiter le format JSON, par exemple le processeur JSON en ligne de commande jq.
Avant de commencer, rassemblez quelques informations de base spécifiques à votre configuration Checkmk :
| Variable | Exemple de valeur | Signification |
|---|---|---|
|
|
Nom d'hôte du serveur Checkmk |
|
|
Nom de l'instance Checkmk |
|
|
Nom de l'utilisateur de l'automatisation |
|
|
Le mot de passe de l'utilisateur de l'automatisation |
Ces variables sont utilisées dans l'exemple de code et doivent être éditées par vos soins avant d'envoyer une requête. Dans le tableau ci-dessus, vous trouverez également les exemples de valeurs utilisées ci-après.
3.4. Envoyer des requêtes à l'aide de scripts
À l'aide d'un exemple simple, nous allons maintenant vous montrer comment utiliser l'API REST. Créez un ordinateur hôte avec ses services à l'aide de quatre requêtes au total. En principe, vous procédez de la même manière que vous le feriez avec l'interface graphique de Checkmk :
Créez un ordinateur hôte
Effectuez une reconnaissance du service sur l'ordinateur hôte
Afficher les modifications en attente
Activer les modifications
Création d'un ordinateur hôte
Ouvrez la documentation de l'API et sélectionnez l'entrée relative à la création d'un ordinateur hôte (Create a host) dans la zone de navigation de gauche :
Dans la partie centrale du panneau, vous pouvez voir les détails de la requête sélectionnée, l'authentification HTTP requise (celle-ci est identique pour toutes les requêtes via l'API REST), ainsi que les paramètres obligatoires et facultatifs. Le nom de l'hôte et le dossier dans lequel il doit être créé sont obligatoires. Par défaut, l'hôte est créé dans le dossier Main. Si vous souhaitez créer l'ordinateur hôte dans un autre dossier, vous devrez peut-être d'abord effectuer une autre requête API (Show all folders) pour afficher les dossiers existants et déterminer l'ID de celui que vous souhaitez utiliser.
Dans notre exemple, l'ordinateur hôte myhost123 doit être créé avec l'adresse IP 192.168.0.42 dans le dossier Main.
Dans la documentation de l'API, cliquez sur le bouton curl dans la zone d'exemple à droite, puis cliquez sur Copy pour copier l'exemple de code curl dans le presse-papiers.
Ouvrez le script préparé create_host.sh et collez-y le contenu du presse-papiers :
Dans la première partie de l'exemple de code, vous trouverez les variables d'environnement, puis vient l'instruction curl avec la méthode POST sur la ressource dont l'URL figure à la dernière ligne.
L'option -write-out affiche enfin une ligne avec le code HTTP.
Les lignes d'en-tête (dont l'une définit l'authentification HTTP) sont suivies de la section de données dans laquelle les paramètres du nouvel hôte sont définis.
Notez que l'exemple de code curl peut contenir plus de paramètres que ce dont vous pourriez avoir besoin dans une situation spécifique.
Dans notre exemple, ce n'est pas le cas et vous n'avez qu'à modifier les deux paramètres existants, host_name et ipaddress.
Modifiez maintenant l'exemple de code afin que le résultat ressemble à ceci :
Exécutez le script :
Rappel : la ligne unique au format JSON délimitée par des accolades est affichée ici sur plusieurs lignes.
L'API renvoie sous links une sélection de requêtes (abrégées dans notre exemple ci-dessus), qui peuvent être appliquées à l'hôte qui vient d'être créé — comme il sied à une API REST.
Enfin, l'API renvoie l'ID et le nom (title) de l'hôte créé, le nom de l'folder (/ pour le dossier Main) et l'attributese attribué à l'hôte, y compris l'adresse IP.
Enfin, la ligne contenant le code HTTP est affichée.
L'200e signifie « OK » et indique que l'action s'est déroulée avec succès.
Effectuer la reconnaissance du service sur l'ordinateur hôte
Une fois l'myhost123 de l'ordinateur hôte créée, ses services peuvent être détectés.
Pour vous assurer que la reconnaissance du service fournit bien les services attendus, vous devez d'abord installer et enregistrer les agents respectifs sur les ordinateurs hôtes Linux et Windows.
Pour exécuter la reconnaissance du service via l'API REST, sélectionnez l'entrée appropriée dans la documentation de l'API (Execute a service discovery on a host), copiez l'exemple de code dans le fichier de script créé à cet effet et adaptez-le.
Vous pouvez copier la première partie avec les variables d'environnement à l'identique depuis l'exemple précédent.
Dans l'instruction curl, remplacez le nom de domaine par myhost123 et, si nécessaire, utilisez le paramètre mode pour modifier le type de reconnaissance du service.
Exécutez également ce script :
Dans ce cas, le code HTTP 303 signifie que la tâche d'arrière-plan pour la reconnaissance du service a été initialisée.
Afficher les modifications en attente
Avant d'activer les modifications, une étape intermédiaire est nécessaire : l'affichage des modifications en attente à l'aide de la requête Show all pending changes. Outre les modifications qui se sont accumulées, l'API REST fournit également l'ETag HTTP (entity tag) dont vous avez besoin pour activer ces modifications. Un objet n'est pas modifié via l'API REST à l'aide de son ID ou de son titre. À la place, l'ETag généré est utilisé pour empêcher que plusieurs requêtes concurrentes n'écrasent les valeurs d'un même objet.
L'ETag est renvoyé dans l'en-tête de réponse.
Pour afficher cet en-tête, étendez le code d'exemple de cette requête en appelant curl avec l'option -i (pour inclure les en-têtes de réponse).
Les lignes modifiées sont également à nouveau marquées dans l'exemple suivant :
Une fois le script exécuté, les lignes d'en-tête s'affichent en premier dans la sortie :
Pour plus de clarté, la sortie est ici raccourcie et seules les lignes importantes sont mises en évidence : la ligne d'en-tête avec l'ETag, les attributs des modifications en attente pour créer un ordinateur hôte et le code HTTP pour OK.
Vous aurez besoin de l'ETag lors de l'étape suivante et finale.
Activer les modifications
Enfin, les modifications doivent être activées. La requête appropriée s'appelle Activate pending changes.
Dans l'instruction curl, remplacez la ligne d'en-tête If-Match et insérez l'ETag lu dans la section précédente.
Dans la section des données, remplacez le paramètre sites et définissez-le sur le nom du site sur lequel les modifications doivent être activées :
Exécutez ce script :
Le texte « title » indique que l'activation a été lancée.
Une fois encore, l'API REST propose deux requêtes de suivi utiles sous « links » :
pour interroger l'état de cette activation et pour attendre qu'elle soit terminée.
3.5. Envoyer des requêtes via l'interface graphique de l'API REST
L'interface graphique de l'API REST vous offre une nouvelle perspective sur l'API. Grâce à cette interface, vous pouvez interagir directement avec l'API depuis le navigateur en envoyant des requêtes au serveur via des instructions curl, et voir immédiatement les réponses. Pour ce faire, vous devez vous passer des exemples de code de la documentation de l'API REST dans l'interface graphique de l'API — les deux vues sont optimisées pour leurs fonctions respectives.
L'interface graphique de l'API REST est générée à partir de la même source que la documentation de l'API REST — le document OpenAPI — et fournit donc toujours des fonctions qui correspondent à l'API.
Vous ouvrez l’interface graphique de l’API dans l’interface graphique de Checkmk à partir de la barre de navigation, menu «Help > Developer resources > REST API interactive GUI». L’interface graphique de l’API s’affiche dans une nouvelle fenêtre (ou un nouvel onglet) du navigateur :
Nous vous expliquons ci-dessous comment exécuter la première requête de l'exemple ci-dessus (créer un ordinateur hôte) à l'aide de l'interface graphique de l'API REST plutôt qu'à l'aide d'un script :
Authentification : L'interface graphique de l'API REST propose une boîte de dialogue permettant de saisir les informations d'authentification après avoir cliqué sur le bouton « Authorize » (situé à droite, au-dessus de l'entrée du premier dossier de ressources). Toutefois, si vous êtes connecté en tant qu'utilisateur de l'instance, vous n'avez pas besoin d'effectuer de saisie à cet endroit, car vous êtes autorisé à utiliser l'API REST en tant qu'utilisateur Checkmk via l'authentification par cookie.
Sélectionnez la ressource : Dans le dossier « Hosts », sélectionnez la ressource « Create a host » et cliquez sur « Try it out ».
Saisissez les valeurs des paramètres : Dans Request body, remplacez les valeurs d'exemple pour
host_nameetipaddress.Envoyez une requête : Cliquez sur « Execute ».
Vérifiez la réponse : Sous Responses, vous verrez d'abord l'instruction curl envoyée et l'URL de la ressource. Ensuite, sous Server response, la réponse s'affiche avec le code HTTP et sous Responses avec la réponse de l'API REST (formatée sur plusieurs lignes).
L'interface graphique de l'API REST vous offre donc la possibilité de tester rapidement et facilement les fonctionnalités de l'API, et de vous familiariser avec les fonctions des valeurs d'entrée ainsi qu'avec les réponses concrètes.
3.6. Correction des erreurs
Contrairement aux résultats des instructions réussies via le script présentés jusqu'à présent, l'API REST vous indique les erreurs de la manière suivante :
{
"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=401Selon l'erreur, les paramètres affichés dans la sortie peuvent varier.
Cependant, à l'adresse status, le code HTTP, et à l'adresse title, vous obtenez toujours une brève description de la cause de l'erreur.
Dans la plupart des cas, detail vous fournira des informations détaillées, comme son nom l'indique.
Dans l'exemple ci-dessus, vous pouvez voir qu'il y a des modifications en attente dans Checkmk, mais celles-ci ont été initiées par un autre utilisateur.
Par défaut, seules les modifications qui ont également été effectuées via l'API peuvent être activées via l'API.
Dans l'exemple suivant, les messages d'aide figurent également dans les informations détaillées :
{
"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=400Le problème dans l'exemple ci-dessus est qu'une valeur de paramètre ne respecte pas la plage de valeurs valide, car le nom de domaine contient une barre oblique.
Le nombre d'erreurs possibles est bien sûr bien plus important que les deux que nous avons présentées ici. Cependant, vous pouvez constater à partir des exemples présentés que, dans sa sortie, l'API REST fournit généralement des informations suffisantes sur la cause et vous donne ainsi des indices pour commencer l'analyse et le dépannage.
4. Sécurisation de l'API
Étant donné que des données sensibles peuvent être transférées lors de l'accès via l'API REST et que, selon les autorisations accordées à l'utilisateur de l'automatisation, des modifications importantes pourraient être apportées à Checkmk, vous devez sécuriser cet accès en conséquence. Vous trouverez ici quelques-unes des options disponibles :
Checkmk via HTTPS : Utilisez l'API exclusivement via le protocole HTTPS (Hypertext Transfer Protocol Secure), sinon les noms d'utilisateur, les mots de passe et les données de configuration seront transmis en clair sur le réseau.
Attribuez à l'utilisateur de l'automatisation un mot de passe d'une longueur suffisante. Étant donné que le mot de passe n'est généralement stocké que dans un script, vous pouvez facilement en attribuer un très long.
Veillez à accorder une attention particulière au concept d'autorisation pour les scripts que vous utilisez afin d'envoyer des requêtes à l'API. Ces scripts peuvent contenir des données sensibles telles que des données de configuration, des mots de passe, etc. Assurez-vous donc que seuls les utilisateurs et groupes autorisés puissent lire ces scripts.
5. Exemples de requêtes via l'API REST
Dans ce chapitre, vous trouverez des exemples illustrant comment effectuer des actions courantes à l'aide de l'API REST.
Ces exemples s'appuient à nouveau sur l'exemple de code du programme en ligne de commande curl.
Contrairement à la procédure décrite dans le chapitre Utilisation de l'API, les requêtes sont ici effectuées sous forme d'instructions curl en ligne de commande plutôt que par le biais d'un script.
Cela vous permet d'essayer nos exemples immédiatement, après les avoir adaptés à votre propre environnement.
Afin de présenter les instructions de manière claire ici, nous n’avons indiqué que les lignes de l’exemple de code qui sont absolument nécessaires à l’exécution de l’instruction.
Comme pour l'exemple de code de la documentation de l'API, les exemples de ce chapitre contiennent des variables permettant de construire l'URL de base de l'API REST sur votre serveur Checkmk et de définir les informations d'identification de l'utilisateur de l'automatisation pour l'authentification Bearer utilisée :
| Variable | Exemple de valeur | Description |
|---|---|---|
|
|
Nom du serveur Checkmk |
|
|
Nom de l'instance Checkmk |
|
|
URL de base de l'API REST |
|
|
Nom de l'utilisateur de l'automatisation |
|
|
Mot de passe de l'utilisateur de l'automatisation |
Avant d'exécuter les instructions curl, vous pouvez adapter les variables à votre environnement à l'aide des commandes shell suivantes :
5.1. Ordinateurs hôtes et dossiers
Les requêtes décrites dans ce chapitre se trouvent dans la documentation de l'API, dans les sous-dossiers Hosts et Folders. Les titres des ressources respectives contenues dans la documentation de l'API correspondent aux rubriques suivantes.
Afficher tous les dossiers
Tous les dossiers de la Configuration sont affichés ici — de manière récursive à partir du dossier Main — sans établir de liste des ordinateurs hôtes qu’ils contiennent :
Afficher tous les ordinateurs hôtes d'un dossier
Les ordinateurs hôtes du sous-dossier « Main > Linux » sont ici demandés :
Créer un dossier
Un sous-dossier « Production Hosts » est créé ici dans « Main > Linux » — dans le système de fichiers sous la forme du répertoire « production_hosts ».
Le nouveau dossier se voit ainsi attribuer la balise de l’hôte « Productive system » issue du groupe de balises de l’hôte prédéfini « Criticality » :
Créer un ordinateur hôte
Ici, dans le dossier Main > Linux > Production Hosts, l’ordinateur hôte mylinuxserver est créé avec l’adresse IP 192.168.0.123 et la balise de l’hôte Use piggyback data from other hosts if present :
Afficher un ordinateur hôte
En affichant un ordinateur hôte, vous obtenez une liste des attributs qui lui sont assignés. Cela fournit en outre l'ETag HTTP (balise d'entité) dont vous avez besoin pour pouvoir modifier un ordinateur hôte. Vous trouverez plus d'informations sur l'ETag dans la section Afficher les modifications en attente.
L'ETag est renvoyé dans l'en-tête de réponse.
Pour afficher cet en-tête, appelez curl avec l'option -v (pour un affichage détaillé).
Ici, l'ordinateur hôte mylinuxserver est interrogé — et seule la ligne contenant l'ETag est affichée à partir de la réponse :
Mettre à jour un ordinateur hôte
Avant d’effectuer la modification, récupérez l’ETag de cet hôte comme décrit dans la section précédente Afficher un hôte.
Vous devez ensuite saisir l’ETag dans l’en-tête de la requête sous « If-Match ».
Ici, la balise de l’hôte du groupe « Piggyback » qui avait été spécifiée lors de la création de l’hôte est supprimée, et la balise prédéfinie « API integrations if configured, else Checkmk agent » est spécifiée pour la remplacer :
Exécuter une reconnaissance du service sur un ordinateur hôte
Pour vous assurer qu’une reconnaissance du service fournit bien les services attendus, vous devez d’abord installer et enregistrer les agents de supervision respectifs sur les ordinateurs hôtes Linux et Windows.
Ici, la reconnaissance du service est effectuée sur l'ordinateur hôte mylinuxserver avec l'option tabula_rasa, qui correspond au bouton « Remove all and find new » dans l'interface graphique de Checkmk :
Création groupée d'ordinateurs hôtes
Ici, deux hôtes sont créés dans le dossier Main > Linux > Production Hosts : le premier hôte avec uniquement une adresse IP, et le second hôte avec un hôte parent et deux étiquettes en plus de son adresse IP :
Activer les modifications en attente
Avant de pouvoir entreprendre l'opération complexe consistant à renommer un ordinateur hôte, il est nécessaire d'activer toutes les modifications qui se sont accumulées dans son environnement de configuration.
Ici, les modifications pour l'instance mysite sont toutes activées en une seule opération :
Renommer un ordinateur hôte
Un nouveau nom va également modifier l'hôte.
Par conséquent, récupérez d'abord l'ETag actuel de l'hôte, par exemple à partir de mylinuxserver, comme décrit dans la section Afficher un hôte, et saisissez-le dans l'en-tête de requête sous If-Match.
Ici, l'hôte est renommé mylinuxserver01 :