This is a translation of the original English documentation page. Help us make it better.

Annexe 1. Commentaire de référence

Notation

Types de données

L'API Zabbix supporte les types de données suivant :

Type Description
boolean Une valeur booléenne, accepte soit true soit false (vrai ou faux).
flag Une valeur est considérée comme étant true si elle est validée ou non égale à null et false sinon.
integer Un nombre entier.
float Un nombre à virgule flottante.
string Une chaîne de texte.
text Une chaîne de texte plus longue.
timestamp Un timestamp Unix (horodatage).
array Une séquence ordonnée de valeurs, c'est-à-dire un tableau simple.
object Un tableau associatif.
query Une valeur qui définit quelles données doivent être renvoyées.

Peut être défini comme un tableau de noms de propriétés ne renvoyant que des propriétés spécifiques ou comme l’une des valeurs prédéfinies :
extend - renvoie toutes les propriétés de l’objet ;
count - retourne le nombre d'enregistrements récupérés, supportés uniquement par certaines sous-sélections.

Étiquettes de propriétés

Certaines propriétés des objets sont marquées par de courtes étiquettes décrivant leur comportement. Les étiquettes suivantes sont utilisées :

  • readonly - la valeur de la propriété est définie automatiquement et ne peut pas être définie ou modifiée par le client (lecture seule) ;
  • constante - la valeur de la propriété peut être définie lors de la création d'un objet, mais ne peut pas être modifiée après.

Valeur d'ID réservée "0"

La valeur d'ID réservée "0" peut être utilisée pour filtrer des éléments et pour supprimer des objets référencés. Par exemple, pour supprimer un proxy référencé d'un hôte, proxy_hostid doit être défini sur 0 ("proxy_hostid": "0") ou pour filtrer les hôtes surveillés par le serveur, l'option proxyids doit être définie sur 0 ("proxyids": "0").

Paramètres communs de la méthode "get"

Les paramètres suivants sont supportés par toutes les méthodes get :

|Paramètre|Type|Description| |---------|------|---------------------------------------------------|¶ |countOutput|boolean|Renvoie le nombre d'enregistrements dans le résultat au lieu des données réelles.| |editable|boolean|Si positionné sur true retourne seulement les objets sur lequels l'utilisateurs dispose d'authorisations.

Par défaut : false.| |excludeSearch|boolean|Retourne les résultats qui ne correspondent pas aux critères indiqués dans le paramètre search.| |filter|object|Retourne uniquement les résultats qui correspondent exactement au filtre donné.

Accepte un tableau, où les clés sont des noms de propriétés, et les valeurs sont soit une valeur simple soit un tableau de valeurs qui correspondent.

Ne fonctionne pas pour les champs text.| |limit|integer|Limite du nombre d'enregistrements retournés.| |output|query|Propriétés de l'objet a retourner.

Par défaut : extend.| |preservekeys|boolean|Utilise les IDs comme clés dans le tableau renvoyé.| |search|object|Retourne les resultats qui correspondent à la recherche générique donnée (sensible à la casse).

Accepte un tableau, où les clés sont des noms de propriétés, et les valeurs sont des chaînes à rechercher. Si aucune option supplémentaire n'est spécifiée, cela effectuera une recherche LIKE "%…%".

Fonctionne seulement pour les champs string et text.| |searchByAny|boolean|Si positionné sur true retourne les résultats qui correspondent n'importe quel critère spécifié dans le paramètre filter ou search au lieu de tous.

Par défaut : false.| |searchWildcardsEnabled|boolean|Si positionné sur true active l'utilisation de "*" comme caractère générique dans le paramètre search.

Par défaut : false.| |sortfield|string/array|Trie le résultat en fonction des propriétés données. Reportez-vous à la description de la méthode get de l'API spécifique pour obtenir une liste des propriétés pouvant être utilisées pour le tri. Les macros ne sont pas développées avant le tri.

Si aucune valeur n'est spécifiée, les données seront retournées non triées.| |sortorder|string/array|Ordre de tri. Si un tableau est donné, chaque valeur correspond à la propriété correspondante indiquée dans le paramètre sortfield.

Les valeurs possibles sont :
ASC - croissant ;
DESC - décroissant. (par défaut)| |startSearch|boolean|Le paramètre search comparera le début des champs, c'est-à-dire qu'il effectuera une recherche LIKE "…%" à la place.

Ignoré si searchWildcardsEnabled est défini sur true.|

Exemples

Vérifications des permissions utilisateur

L'utilisateur est-il autorisé à écrire sur des hôtes dont le nom commence par "MySQL" ou "Linux" ?

Requête :

{
           "jsonrpc": "2.0",
           "method": "host.get",
           "params": {
               "countOutput": true,
               "search": {
                   "host": ["MySQL", "Linux"]
               },
               "editable": true,
               "startSearch": true,
               "searchByAny": true
           },
           "auth": "766b71ee543230a1182ca5c44d353e36",
           "id": 1
       }

Réponse :

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

Le résultat Zéro signifie qu'il n'y a aucun hôte avec des autorisations en lecture/écriture.

Comptage des erreurs

Compte le nombre d'hôtes dont le nom ne contient pas la sous-chaîne "ubuntu"

Requête :

{
           "jsonrpc": "2.0",
           "method": "host.get",
           "params": {
               "countOutput": true,
               "search": {
                   "host": "ubuntu"
               },
               "excludeSearch": true
           },
           "auth": "766b71ee543230a1182ca5c44d353e36",
           "id": 1
       }

Réponse :

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

Recherche d'hôtes à l'aide de caractères génériques

Recherche les hôtes dont le nom contient le mot "server" et dont les ports d'interface sont "10050" ou "10071". Trie le résultat par nom d’hôte par ordre décroissant et le limite à 5 hôtes.

Requête :

{
        "jsonrpc": "2.0",
        "method": "host.get",
        "params": {
        "output": ["hostid", "host"],
        "selectInterfaces": ["port"],
        "filter": {
        "port": ["10050", "10071"]
        },
        "search": {
        "host": "*server*"
        },
        "searchWildcardsEnabled": true,
        "searchByAny": true,
        "sortfield": "host",
        "sortorder": "DESC",
        "limit": 5
        },
        "auth": "766b71ee543230a1182ca5c44d353e36",
        "id": 1
       }

Réponse :

{
        "jsonrpc": "2.0",
        "result": [
        {
        "hostid": "50003",
        "host": "WebServer-Tomcat02",
        "interfaces": [
        {
        "port": "10071"
        }
        ]
        },
        {
        "hostid": "50005",
        "host": "WebServer-Tomcat01",
        "interfaces": [
        {
        "port": "10071"
        }
        ]
        },
        {
        "hostid": "50004",
        "host": "WebServer-Nginx",
        "interfaces": [
        {
        "port": "10071"
        }
        ]
        },
        {
        "hostid": "99032",
        "host": "MySQL server 01",
        "interfaces": [
        {
        "port": "10050"
        }
        ]
        },
        {
        "hostid": "99061",
        "host": "Linux server 01",
        "interfaces": [
        {
        "port": "10050"
        }
        ]
        }
        ],
        "id": 1
       }

Recherche d'hôtes à l'aide de caractères génériques avec "preservekeys"

Si vous ajoutez le paramètre "preservekeys" à la requête précédente, le résultat est renvoyé sous la forme d'un tableau associatif, où les clés sont les identifiants des objets.

Requête :

{
           "jsonrpc": "2.0",
           "method": "host.get",
           "params": {
               "output": ["hostid", "host"],
               "selectInterfaces": ["port"],
               "filter": {
                   "port": ["10050", "10071"]
               },
               "search": {
                   "host": "*server*"
               },
               "searchWildcardsEnabled": true,
               "searchByAny": true,
               "sortfield": "host",
               "sortorder": "DESC",
               "limit": 5,
               "preservekeys": true
           },
           "auth": "766b71ee543230a1182ca5c44d353e36",
           "id": 1
       }

Réponse :

{
           "jsonrpc": "2.0",
           "result": {
               "50003": {
                   "hostid": "50003",
                   "host": "WebServer-Tomcat02",
                   "interfaces": [
                       {
                           "port": "10071"
                       }
                   ]
               },
               "50005": {
                   "hostid": "50005",
                   "host": "WebServer-Tomcat01",
                   "interfaces": [
                       {
                           "port": "10071"
                       }
                   ]
               },        
               "50004": {
                   "hostid": "50004",
                   "host": "WebServer-Nginx",
                   "interfaces": [
                       {
                           "port": "10071"
                       }
                   ]
               },
               "99032": {
                   "hostid": "99032",
                   "host": "MySQL server 01",
                   "interfaces": [
                       {
                           "port": "10050"
                       }
                   ]
               },
               "99061": {
                   "hostid": "99061",
                   "host": "Linux server 01",
                   "interfaces": [
                       {
                           "port": "10050"
                       }
                   ]
               }
           },
           "id": 1
       }