20 API

Vue d'ensemble

L'API Zabbix vous permet de récupérer et de modifier par programmation la configuration de Zabbix et fournit un accès aux données historiques. Elle est largement utilisée pour :

  • Créer de nouvelles applications pour fonctionner avec Zabbix.
  • Intégrer Zabbix dans un logiciel tiers.
  • Automatiser les tâches de routine.

L'API Zabbix est une API basée sur HTTP, et elle est fournie en tant que partie de l'interface. Elle utilise le protocole JSON-RPC 2.0, ce qui signifie deux choses :

  • L'API se compose d'un ensemble de méthodes distinctes.
  • Les requêtes et les réponses entre les clients et l'API sont encodées au format JSON.

Pour plus d'informations sur le protocole et JSON, consultez la spécification JSON-RPC 2.0 et la page d'accueil du format JSON.

Pour plus d'informations sur l'intégration des fonctionnalités Zabbix dans vos applications Python, consultez Python library for Zabbix.

L'accès des utilisateurs dans Zabbix, y compris la configuration et les données historiques, dépend du type d'utilisateur, du rôle utilisateur attribué et des groupes d'utilisateurs.

Structure

L'API se compose d'un certain nombre de méthodes qui sont nominalement regroupées en API distinctes. Chacune des méthodes effectue une tâche spécifique. Par exemple, la méthode host.create appartient à l'API host et est utilisée pour créer de nouveaux hôtes. Historiquement, les API sont parfois appelées des "classes".

La plupart des API contiennent au moins quatre méthodes: get, create, update et delete pour récupérer, créer, mettre à jour et supprimer des données respectivement, mais certaines API peuvent fournir un ensemble de méthodes totalement différent.

Exécution de requêtes

Une fois l'interface configurée, vous pouvez utiliser des requêtes HTTP distantes pour appeler l'API. Pour ce faire, vous devez envoyer des requêtes HTTP POST au fichier api_jsonrpc.php situé dans le répertoire de l'interface.
Par exemple, si votre interface Zabbix est installée sous https://example.com/zabbix, une requête HTTP pour appeler la méthode apiinfo.version peut ressembler à ceci :

curl --request POST \
  --url 'https://example.com/zabbix/api_jsonrpc.php' \
  --header 'Content-Type: application/json-rpc' \
  --data '{"jsonrpc":"2.0","method":"apiinfo.version","params":{},"id":1}'

La requête doit avoir l'en-tête Content-Type défini sur l'une de ces valeurs : application/json-rpc, application/json ou application/jsonrequest.

L'objet de requête doit contenir les propriétés suivantes :

  • jsonrpc - la version du protocole JSON-RPC utilisée par l'API (l'API Zabbix implémente la version 2.0 de JSON-RPC) ;
  • method - la méthode de l'API appelée ;
  • params - les paramètres qui seront transmis à la méthode de l'API ;
  • id - un identifiant arbitraire de la requête (s'il est omis, l'API traite la requête comme une notification).

Si la requête est correcte, la réponse renvoyée par l'API doit ressembler à ceci :

{
    "jsonrpc": "2.0",
    "result": "7.0.0",
    "id": 1
}

L'objet de réponse, quant à lui, contient les propriétés suivantes :

  • jsonrpc - la version du protocole JSON-RPC ;
  • result - les données renvoyées par la méthode ;
  • id - un identifiant de la requête correspondante.

Authentification

Pour accéder à des données dans Zabbix, vous devez soit :

  • Utiliser un jeton API existant créé dans l'interface Zabbix, section Users > API tokens, ou créé à l'aide de l'API Token.
  • Utiliser un jeton d'authentification obtenu avec la méthode user.login.

Par exemple, si vous souhaitez obtenir un nouveau jeton d'authentification en vous connectant en tant qu'utilisateur Admin standard, une requête JSON ressemblerait à ceci :

curl --request POST \
  --url 'https://example.com/zabbix/api_jsonrpc.php' \
  --header 'Content-Type: application/json-rpc' \
  --data '{"jsonrpc":"2.0","method":"user.login","params":{"username":"Admin","password":"zabbix"},"id":1}'

Si vous avez fourni les identifiants correctement, la réponse renvoyée par l'API doit contenir le jeton d'authentification de l'utilisateur :

{
    "jsonrpc": "2.0",
    "result": "0424bd59b807674191e7d77572075f33",
    "id": 1
}

Méthodes d'autorisation

Par en-tête Authorization

Toutes les requêtes API nécessitent une authentification ou un jeton API. Vous pouvez fournir les identifiants en utilisant l'en-tête Authorization dans la requête :

curl --request POST \
  --url 'https://example.com/zabbix/api_jsonrpc.php' \
  --header 'Authorization: Bearer 0424bd59b807674191e7d77572075f33'

Si vous rencontrez des problèmes d'authentification, consultez Transfert de l'en-tête Authorization.

Depuis Zabbix 7.0.7, l'en-tête Authorization est pris en charge dans les requêtes inter-origines (CORS). Depuis Zabbix 7.0.11, l'API Zabbix accepte les en-têtes sans distinction de casse (par exemple, authorization, Authorization et AUTHORIZATION sont traités de la même manière).

Par la propriété auth

Une requête API peut être autorisée par la propriété auth.

Notez que l'utilisation de cette propriété auth est dépréciée. Elle sera supprimée dans une future version.

curl --request POST \
  --url 'https://example.com/zabbix/api_jsonrpc.php' \
  --header 'Content-Type: application/json-rpc' \
  --data '{"jsonrpc":"2.0","method":"host.get","params":{"output":["hostid"]},"auth":"0424bd59b807674191e7d77572075f33","id":1}'

Un cookie "zbx_session" est utilisé pour autoriser une requête API depuis l'interface utilisateur Zabbix effectuée à l'aide de JavaScript (à partir d'un module ou d'un widget personnalisé).

Exemple de flux de travail

La section suivante vous guide à travers plusieurs exemples d'utilisation plus en détail.

Récupération des hôtes

Vous disposez maintenant d'un jeton d'authentification utilisateur valide (représenté par une variable dans les exemples suivants) qui peut être utilisé pour accéder aux données dans Zabbix. Par exemple, vous pouvez utiliser la méthode host.get pour récupérer les IDs, les noms d'hôte et les interfaces de tous les hôtes configurés :

Requête :

curl --request POST \
  --url 'https://example.com/zabbix/api_jsonrpc.php' \
  --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \
  --header 'Content-Type: application/json-rpc' \
  --data @data.json

data.json est un fichier qui contient une requête JSON. Au lieu d'un fichier, vous pouvez transmettre la requête dans l'argument --data.

data.json

{
    "jsonrpc": "2.0",
    "method": "host.get",
    "params": {
        "output": [
            "hostid",
            "host"
        ],
        "selectInterfaces": [
            "interfaceid",
            "ip"
        ]
    },
    "id": 2
}

L'objet de réponse contiendra les données demandées sur les 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 performance, il est toujours recommandé de lister les propriétés de l'objet que vous souhaitez récupérer. Ainsi, vous éviterez de tout récupérer.

Création d'un nouvel élément

Maintenant, créez un nouvel élément sur l'hôte "Zabbix server" en utilisant les données que vous avez obtenues à partir de la requête host.get précédente. Cela peut être fait à l'aide de la méthode item.create :

curl --request POST \
  --url 'https://example.com/zabbix/api_jsonrpc.php' \
  --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \
  --header 'Content-Type: application/json-rpc' \
  --data '{"jsonrpc":"2.0","method":"item.create","params":{"name":"Free disk space on /home/joe/","key_":"vfs.fs.size[/home/joe/,free]","hostid":"10084","type":0,"value_type":3,"interfaceid":"1","delay":30},"id":3}'

Une réponse réussie contiendra l'ID du nouvel élément créé, qui pourra être utilisé pour référencer l'élément dans les requêtes suivantes :

{
    "jsonrpc": "2.0",
    "result": {
        "itemids": [
            "24759"
        ]
    },
    "id": 3
}

La méthode item.create, ainsi que d'autres méthodes de création, peut également accepter des tableaux d'objets et créer plusieurs éléments en une seule appel d'API.

Création de plusieurs déclencheurs

Ainsi, si les méthodes de création acceptent des tableaux, vous pouvez ajouter plusieurs déclencheurs, par exemple celui-ci :

curl --request POST \
  --url 'https://example.com/zabbix/api_jsonrpc.php' \
  --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \
  --header 'Content-Type: application/json-rpc' \
  --data '{"jsonrpc":"2.0","method":"trigger.create","params":[{"description":"Processor load is too high on {HOST.NAME}","expression":"last(/Linux server/system.cpu.load[percpu,avg1])>5"},{"description":"Too many processes on {HOST.NAME}","expression":"avg(/Linux server/proc.num[],5m)>300"}],"id":4}'

La réponse réussie contiendra les identifiants des déclencheurs nouvellement créés :

{
    "jsonrpc": "2.0",
    "result": {
        "triggerids": [
            "17369",
            "17370"
        ]
    },
    "id": 4
}

Mise à jour d'un élément

Activez un élément en définissant son statut sur 0 :

curl --request POST \
  --url 'https://example.com/zabbix/api_jsonrpc.php' \
  --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \
  --header 'Content-Type: application/json-rpc' \
  --data '{"jsonrpc":"2.0","method":"item.update","params":{"itemid":"10092","status":0},"id":5}'

La réponse réussie contiendra l'ID de l'élément mis à jour :

{
    "jsonrpc": "2.0",
    "result": {
        "itemids": [
            "10092"
        ]
    },
    "id": 5
}

La méthode item.update, ainsi que les autres méthodes de mise à jour, peut également accepter des tableaux d'objets et mettre à jour plusieurs éléments avec un seul appel API.

Mise à jour de plusieurs déclencheurs

Activez plusieurs déclencheurs en définissant leur statut sur 0 :

curl --request POST \
  --url 'https://example.com/zabbix/api_jsonrpc.php' \
  --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \
  --header 'Content-Type: application/json-rpc' \
  --data '{"jsonrpc":"2.0","method":"trigger.update","params":[{"triggerid":"13938","status":0},{"triggerid":"13939","status":0}],"id":6}'

La réponse réussie contiendra les ID des déclencheurs mis à jour :

{
    "jsonrpc": "2.0",
    "result": {
        "triggerids": [
            "13938",
            "13939"
        ]
    },
    "id": 6
}

Il s'agit de la méthode de mise à jour recommandée. Certaines méthodes API, comme host.massupdate, permettent d'écrire un code plus simple. Cependant, il n'est pas recommandé d'utiliser ces méthodes, car elles seront supprimées dans les futures versions.

Gestion des erreurs

Jusqu'à présent, tout ce que vous avez essayé a fonctionné correctement. Mais que se passerait-il si vous essayiez d'effectuer un appel incorrect à l'API ? Essayez de créer un autre hôte en appelant host.create tout en omettant le paramètre obligatoire groups :

curl --request POST \
  --url 'https://example.com/zabbix/api_jsonrpc.php' \
  --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \
  --header 'Content-Type: application/json-rpc' \
  --data '{"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}'

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 s'est produite, au lieu de la propriété result, l'objet de réponse contiendra la propriété error avec les données suivantes :

  • code - un code d'erreur ;
  • message - un bref résumé de l'erreur ;
  • data - un message d'erreur plus détaillé.

Des erreurs peuvent survenir dans divers cas, par exemple lors de l'utilisation de valeurs d'entrée incorrectes, d'un dépassement du délai de session ou d'une tentative d'accès à des objets inexistants. Votre application doit être capable de gérer correctement ce type d'erreurs.

Versions de l'API

Pour simplifier le versionnement 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 adapter votre application afin d'utiliser des fonctionnalités spécifiques à une version.

Zabbix garantit la compatibilité ascendante des fonctionnalités au sein d'une version majeure. Lors de changements incompatibles avec les versions précédentes entre des versions majeures, Zabbix laisse généralement les anciennes fonctionnalités comme obsolètes dans la version suivante, puis ne les supprime que dans la version d'après. Il arrive parfois que Zabbix supprime des fonctionnalités entre des versions majeures sans fournir de compatibilité ascendante. Il est important de ne jamais dépendre de fonctionnalités obsolètes et de migrer vers des alternatives plus récentes dès que possible.

Vous pouvez suivre toutes les modifications apportées à l'API dans le journal des modifications de l'API.

Lecture complémentaire

Vous disposez désormais de suffisamment de connaissances pour commencer à travailler avec l'API Zabbix, cependant, ne vous arrêtez pas là. Pour aller plus loin, nous vous conseillons de consulter la liste des API disponibles.