18 API

Aperçu

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

• créer de nouvelles applications fonctionnant avec Zabbix ;
• intégrer Zabbix à un logiciel tiers ;
• automatiser les tâches de routine.

L'API Zabbix est une API basée sur HTTP et elle est fournie comme partie intégrante de l'interface web. 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 de Zabbix dans vos applications Python, consultez la bibliothèque Python pour Zabbix.

Structure

L'API possède 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 host et est utilisée pour créer de nouveaux hôtes. Historiquement, les API sont parfois appelées "classes".

Exécution des requêtes

Une fois le frontend configuré, vous pouvez utiliser des requêtes HTTP distantes pour appeler l’API. Pour cela, vous devez envoyer des requêtes HTTP POST au fichier api_jsonrpc.php situé dans le répertoire du frontend. Par exemple, si votre frontend Zabbix est installé 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 des valeurs suivantes : 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 d’API appelée ;
• params - les paramètres qui seront transmis à la méthode d’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": "8.0.0",
    "id": 1
}

L’objet de réponse, à son tour, 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.

Exemple de flux de travail

La section suivante vous présentera quelques exemples d’utilisation de manière plus détaillée.

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 requête. 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 - un identifiant arbitraire de la requête;
• 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 :

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

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 (ici le token dans cet exemple) ;
• id - identifiant de la requête correspondante.

Méthodes d'autorisation

Par l’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'

L’API Zabbix accepte les en-têtes sans tenir compte de la casse (par exemple, authorization, Authorization et AUTHORIZATION sont traités de la même manière).

L’en-tête Authorization est pris en charge dans les requêtes cross-origin (CORS).

Par le cookie Zabbix

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é).

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 ID, 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

{
    "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
}

Création d'un nouvel élément

Maintenant, 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 /home/joe/",
        "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 valide contiendra l'ID du nouvel élément créé, qui peut être utilisé pour référencer l'élément dans les requêtes suivantes :

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

Création de plusieurs déclencheurs

Donc, comme 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": "last(/Linux server/system.cpu.load[percpu,avg1])>5",
        },
        {
            "description": "Too many processes on {HOST.NAME}",
            "expression": "avg(/Linux server/proc.num[],5m)>300",
        }
    ],
    "auth": "0424bd59b807674191e7d77572075f33",
    "id": 4
}

Une réponse valide contiendra les identifiants des déclencheurs nouvellement créés :

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

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 valide contiendra l'ID de l'élément mis à jour :

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

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 en cas de réussite contiendra les ID des déclencheurs mis à jour :

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

Gestion des erreurs

Jusque-là, tout ce que nous avons essayé a bien fonctionné. Mais, que se passe-t-il si nous tentons 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 - un 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.

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 mettre à jour votre application afin qu'elle utilise les 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 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.

Pour aller plus loin

Vous avez maintenant suffisamment de connaissances pour commencer à travailler avec l’API Zabbix, cependant, ne vous arrêtez pas ici. Pour approfondir le sujet, nous vous conseillons de consulter la liste des API disponibles.