Documentation
Table of Contents
19. API
Aperçu
L'API Zabbix vous permet de récupérer et de modifier par programmation la configuration de Zabbix et donne accès aux données historiques. Elle est largement utilisée pour :
* Créer de nouvelles applications pour s'interfacer avec Zabbix ;
* Intégrer Zabbix avec un logiciel tiers ;
* Automatiser les tâches de routine.L'API Zabbix est une API Web et est fournie avec l'interface Web. Elle utilise le protocole JSON-RPC 2.0, ce qui signifie deux choses :
* L'API consiste en un ensemble de méthodes distinctes ;
* Les demandes et les réponses entre les clients et l'API sont codées au format JSON.Vous trouverez plus d'informations sur le protocole et JSON dans la spécification JSON-RPC 2.0 et la page d'accueil du format JSON.
Structure
L'API consiste en un certain nombre de méthodes qui sont nominalement regroupées dans des API distinctes. Chacune des méthodes effectue une tâche spécifique. Par exemple, la méthode host.create appartient à l'API Hôte et est utilisée pour créer de nouveaux hôtes. Historiquement, les API sont parfois appelées "classes".
- La plupart des API contiennent au moins quatre méthodes
get,create,updateet ''delete '' pour respectivement récupérer, créer, mettre à jour et supprimer des données, mais certaines API peuvent fournir un ensemble de méthodes totalement différentes.
Effectuer des demandes
Une fois que vous avez configuré l'interface web, vous pouvez utiliser des requêtes HTTP distantes pour appeler l'API. Pour ce faire, vous devez envoyer des demandes HTTP POST au fichier api_jsonrpc.php situé dans le répertoire frontend. Par exemple, si votre interface Zabbix est installée sous http://company.com/zabbix, la requête HTTP permettant d'appeler la méthode apiinfo.version peut ressembler à ceci:
POST http://company.com/zabbix/api_jsonrpc.php HTTP/1.1
Content-Type: application/json-rpc
{"jsonrpc":"2.0","method":"apiinfo.version","id":1,"auth":null,"params":{}}L'en-tête Content-Type de la demande doit être défini sur l'une des valeurs suivantes : application/json-rpc, application/json ou application/jsonrequest.
Vous pouvez utiliser n’importe quel client HTTP ou outil de test JSON-RPC pour exécuter des requêtes d’API manuellement, mais pour le développement d’applications, nous vous suggérons d’utiliser l’une des bibliothèques gérées par la communauté.
Exemple de flux de travail
La section suivante vous guidera à travers quelques exemples d'utilisation plus en détail.
Authentification
Avant de pouvoir accéder aux données de Zabbix, vous devez vous connecter et obtenir un jeton d'authentification. Ceci peut être fait en utilisant la méthode user.login. Supposons que vous souhaitiez vous connecter en tant qu’administrateur Zabbix standard. Votre demande JSON ressemblera à ceci :
{
"jsonrpc": "2.0",
"method": "user.login",
"params": {
"user": "Admin",
"password": "zabbix"
},
"id": 1,
"auth": null
}Examinons de plus près l'objet de la demande. Il a les propriétés suivantes :
* ''jsonrpc'' - version du protocole JSON-RPC utilisée par l'API ; l'API Zabbix implémente JSON-RPC version 2.0 ;
* ''method'' - la méthode API appelée ;
* ''params'' - paramètres qui seront transmis à la méthode API ;
* ''id'' - identifiant arbitraire de la demande ;
* ''auth'' - un jeton d'authentification utilisateur ; comme nous n'en avons pas encore, il est défini à ''null''.Si vous avez correctement fourni les informations d'identification, la réponse renvoyée par l'API contiendra le jeton d'authentification de l'utilisateur :
L'objet de réponse contient à son tour les propriétés suivantes :
* ''jsonrpc'' - encore une fois, la version du protocole JSON-RPC ;
* ''result'' - les données retournées par la méthode ;
* ''id'' - identifiant de la requête correspondante.Récupération des hôtes
Nous avons maintenant un jeton d'authentification utilisateur valide qui peut être utilisé pour accéder aux données dans Zabbix. Par exemple, utilisons la méthode host.get pour récupérer les ID, les noms d'hôtes et les interfaces de tous les hosts
{
"jsonrpc": "2.0",
"method": "host.get",
"params": {
"output": [
"hostid",
"host"
],
"selectInterfaces": [
"interfaceid",
"ip"
]
},
"id": 2,
"auth": "0424bd59b807674191e7d77572075f33"
}Notez que la propriété auth est maintenant définie sur le jeton d'authentification que nous avons obtenu en appelant user.login.
L'objet de réponse contiendra les données demandées au sujet des hôtes :
{
"jsonrpc": "2.0",
"result": [
{
"hostid": "10084",
"host": "Zabbix server",
"interfaces": [
{
"interfaceid": "1",
"ip": "127.0.0.1"
}
]
}
],
"id": 2
}Pour des raisons de performances, nous vous recommandons de toujours répertorier les propriétés d'objet que vous souhaitez récupérer et d'éviter de tout récupérer.
Création d'un nouvel élément
Créons un nouvel élément sur l'hôte "Zabbix server" en utilisant les données que nous avons obtenues de la précédente requête host.get. Cela peut être fait en utilisant la méthode item.create :
{
"jsonrpc": "2.0",
"method": "item.create",
"params": {
"name": "Free disk space on $1",
"key_": "vfs.fs.size[/home/joe/,free]",
"hostid": "10084",
"type": 0,
"value_type": 3,
"interfaceid": "1",
"delay": 30
},
"auth": "0424bd59b807674191e7d77572075f33",
"id": 3
}Une réponse réussie contiendra l'ID du nouvel élément créé, qui peut être utilisé pour référencer l'élément dans les demandes suivantes :
La méthode item.create ainsi que d'autres méthodes de création peuvent également accepter des tableaux d'objets et créer plusieurs éléments avec un seul appel d'API.
Création de plusieurs déclencheurs
Donc, si les méthodes create acceptent les tableaux, nous pouvons ajouter plusieurs déclencheurs comme ceci :
{
"jsonrpc": "2.0",
"method": "trigger.create",
"params": [
{
"description": "Processor load is too high on {HOST.NAME}",
"expression": "{Linux server:system.cpu.load[percpu,avg1].last()}>5",
},
{
"description": "Too many processes on {HOST.NAME}",
"expression": "{Linux server:proc.num[].avg(5m)}>300",
}
],
"auth": "0424bd59b807674191e7d77572075f33",
"id": 4
}Une réponse réussie contiendra les identifiants des déclencheurs nouvellement créés :
Mise à jour d'un élément
Activer un élément, autrement dit, définir son statut à "0" :
{
"jsonrpc": "2.0",
"method": "item.update",
"params": {
"itemid": "10092",
"status": 0
},
"auth": "0424bd59b807674191e7d77572075f33",
"id": 5
}Une réponse réussie contiendra l'ID de l'élément mis à jour :
La méthode item.update ainsi que d'autres méthodes de mise à jour peuvent également accepter des tableaux d'objets et mettre à jour plusieurs éléments avec un seul appel d'API.
Mise à jour de plusieurs déclencheurs
Activer plusieurs déclencheurs, autrement dit, définir leurs statuts à 0 :
{
"jsonrpc": "2.0",
"method": "trigger.update",
"params": [
{
"triggerid": "13938",
"status": 0
},
{
"triggerid": "13939",
"status": 0
}
],
"auth": "0424bd59b807674191e7d77572075f33",
"id": 6
}Une réponse réussie contiendra les identifiants des déclencheurs mis à jour :
C'est la méthode à privilégier pour la mise à jour. Certaines méthodes de l'API telles que host.massupdate permettent d'écrire un code plus simple, mais il n'est pas recommandé d'utiliser ces méthodes, car elles seront supprimées dans les prochaines versions.
Gestion des erreurs
Jusque là, tout ce que nous avons essayé a bien fonctionné. Mais que se passe-t-il si nous essayons de faire un appel incorrect à l'API ? Essayons de créer un autre hôte en appelant la méthode host.create mais en omettant le paramètre obligatoire groups.
{
"jsonrpc": "2.0",
"method": "host.create",
"params": {
"host": "Linux server",
"interfaces": [
{
"type": 1,
"main": 1,
"useip": 1,
"ip": "192.168.3.1",
"dns": "",
"port": "10050"
}
]
},
"id": 7,
"auth": "0424bd59b807674191e7d77572075f33"
}La réponse contiendra alors un message d'erreur :
{
"jsonrpc": "2.0",
"error": {
"code": -32602,
"message": "Invalid params.",
"data": "No groups for host \"Linux server\"."
},
"id": 7
}Si une erreur survient, au lieu de la propriété result, l'objet de réponse contiendra une propriété error avec les données suivantes :
* ''code'' - un code d'erreur ;
* ''message'' - résumé succinct de l'erreur ;
* ''data'' - un message d'erreur plus détaillé.Des erreurs peuvent survenir dans différents cas, tels que l'utilisation de valeurs d'entrée incorrectes, l'expiration du délai d'une session ou la tentative d'accès à des objets non existants. Votre application doit pouvoir gérer ce type d’erreurs avec élégance.
Versions de l'API
Pour simplifier la gestion des versions de l'API, depuis Zabbix 2.0.4, la version de l'API correspond à la version de Zabbix elle-même. Vous pouvez utiliser la méthode apiinfo.version pour connaître la version de l'API avec laquelle vous travaillez. Cela peut être utile pour ajuster votre application afin qu'elle utilise des fonctionnalités spécifiques à la version.
Nous garantissons la compatibilité ascendante des fonctionnalités dans une version majeure. Lorsque nous effectuons des modifications incompatibles entre les versions majeures, nous conservons généralement les anciennes fonctionnalités comme obsolètes dans la version suivante et nous les supprimons ensuite de la version suivante. Parfois, nous pouvons supprimer des fonctionnalités entre les versions majeures sans fournir de compatibilité ascendante. Il est important que vous ne vous reposiez jamais sur des fonctionnalités obsolètes et que vous migriez vers de nouvelles alternatives dès que possible.
Vous pouvez suivre toutes les modifications apportées à l'API dans le journal des modifications de l'API.
Lectures complémentaires
Vous en savez maintenant assez pour commencer à travailler avec l'API Zabbix, mais ne vous arrêtez pas là. Pour en savoir plus, nous vous conseillons de consulter la liste des API disponibles.