Documentation
Table of Contents
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 :
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 :
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 l'identifiant 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
}