Annexe 1. Commentaire de référence
Notation
Types de données
L’API Zabbix prend en charge les types de données suivants en entrée :
| Type | Description |
|---|---|
| ID | Un identifiant unique utilisé pour référencer une entité. |
| boolean | Une valeur booléenne (true ou false). |
| flag | Une valeur considérée comme true si elle est transmise et différente de null ; sinon, la valeur est considérée comme false. |
| integer | Un nombre entier. |
| float | Un nombre à virgule flottante. |
| string | Une chaîne de caractères. |
| text | Une chaîne de texte plus longue. |
| timestamp | Un horodatage Unix. |
| array | Une séquence ordonnée de valeurs (un tableau simple). |
| object | Un tableau associatif. |
| query | Une valeur qui définit les données à renvoyer. La valeur peut être définie comme un tableau de noms de propriétés (pour ne renvoyer que des propriétés spécifiques), ou comme l’une des valeurs prédéfinies suivantes :extend - renvoie toutes les propriétés de l’objet ;count - renvoie le nombre d’enregistrements récupérés, pris en charge uniquement par certaines sous-sélections. |
L’API Zabbix renvoie toujours uniquement des valeurs sous forme de chaînes ou de tableaux.
Comportement des propriétés
Certaines propriétés de l’objet sont marquées par de courtes étiquettes décrivant leur comportement. Les étiquettes suivantes sont utilisées :
- lecture seule - la valeur de la propriété est définie automatiquement et ne peut pas être définie ni modifiée par l’utilisateur, même dans certaines conditions spécifiques (par ex., lecture seule pour les objets hérités ou les objets découverts) ;
- écriture seule - la valeur de la propriété peut être définie, mais ne peut pas être consultée ensuite ;
- 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 par la suite ;
- prise en charge - la valeur de la propriété n’est pas obligatoire, mais elle peut être définie dans certaines conditions spécifiques (par ex., prise en charge si
typeest défini sur "Simple check", "External check", "SSH agent", "TELNET agent" ou "HTTP agent") ; notez toutefois que les propriétés prises en charge peuvent toujours être définies sur leurs valeurs par défaut quelles que soient les conditions ; - obligatoire - la valeur de la propriété doit être définie pour toutes les opérations (à l’exception des opérations get) ou dans certaines conditions spécifiques (par ex., obligatoire pour les opérations de création ; obligatoire si
operationtypeest défini sur "global script" et queopcommand_hstn’est pas défini).
Pour les opérations de mise à jour, une propriété est considérée comme « définie » lorsqu’elle est définie pendant l’opération de mise à jour.
Les propriétés qui ne sont pas marquées par des étiquettes sont facultatives.
Comportement des paramètres
Certains paramètres d’opération sont marqués par de courtes étiquettes afin de décrire leur comportement pour l’opération. Les étiquettes suivantes sont utilisées :
- lecture seule - la valeur du paramètre est définie automatiquement et ne peut pas être définie ni modifiée par l’utilisateur, même dans certaines conditions spécifiques (par exemple, lecture seule pour les objets hérités ou les objets découverts) ;
- écriture seule - la valeur du paramètre peut être définie, mais ne peut pas être consultée ensuite ;
- pris en charge - la valeur du paramètre n’est pas obligatoire, mais peut être définie dans certaines conditions spécifiques (par exemple, pris en charge si
operating_modede l’objet Proxy est défini sur « passive proxy ») ; notez toutefois que les paramètres pris en charge peuvent toujours être définis sur leurs valeurs par défaut, quelles que soient les conditions ; - obligatoire - la valeur du paramètre doit être définie.
Les paramètres qui ne sont pas marqués par des étiquettes sont facultatifs.
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, proxyid doit être défini sur 0 (« proxyid »: « 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 des méthodes "get"
Les paramètres suivants sont pris en charge par toutes les méthodes get :
| Paramètre | Type | Description |
|---|---|---|
| countOutput | boolean | Retourner le nombre d'enregistrements dans le résultat au lieu des données réelles. |
| editable | boolean | Si défini sur true, retourner uniquement les objets pour lesquels l'utilisateur dispose des droits d'écriture.Par défaut : false. |
| excludeSearch | boolean | Retourner les résultats qui ne correspondent pas aux critères indiqués dans le paramètre search. |
| filter | object | Retourner uniquement les résultats qui correspondent exactement au filtre donné. Accepte un objet, où les clés sont des noms de propriétés (par exemple, les propriétés de l'objet Host dans host.get, les propriétés de l'objet Item dans item.get, etc.), et les valeurs sont soit une valeur unique, soit un tableau de valeurs à comparer.Ne prend pas en charge les propriétés de type de données text data type.Notez que certaines méthodes ont une fonctionnalité spécifique pour ce paramètre, décrite sur la page de la méthode (par exemple, le paramètre filter dans host.get prend également en charge les propriétés de l'interface Host). |
| limit | integer | Limiter le nombre d'enregistrements retournés. |
| output | query | Propriétés de l'objet à retourner. Par défaut : extend. |
| preservekeys | boolean | Utiliser les ID comme clés dans le tableau résultant. |
| search | object | Retourner les résultats qui correspondent au motif donné (insensible à la casse). Accepte un objet, où les clés sont des noms de propriétés (par exemple, les propriétés de l'objet Host dans host.get, les propriétés de l'objet Item dans item.get, etc.), et les valeurs sont des chaînes à rechercher. Si aucune option supplémentaire n'est fournie, cela effectuera une recherche LIKE "%…%".Prend uniquement en charge les propriétés de type de données string et text data type.Notez que certaines méthodes ont une fonctionnalité spécifique pour ce paramètre, décrite sur la page de la méthode (par exemple, le paramètre search dans host.get prend également en charge les propriétés de l'interface Host). |
| searchByAny | boolean | Si défini sur true, retourner les résultats qui correspondent à l'un des critères indiqués dans le paramètre filter ou search, au lieu de tous les critères.Par défaut : false. |
| searchWildcardsEnabled | boolean | Si défini sur true, active l'utilisation de "*" comme caractère générique dans le paramètre search.Par défaut : false. |
| sortfield | string/array | Trier le résultat selon les propriétés indiquées. Reportez-vous à la description d'une méthode get spécifique de l'API pour obtenir la 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 sans tri. |
| sortorder | string/array | Ordre de tri. Si un tableau est transmis, chaque valeur sera associée à la propriété correspondante indiquée dans le paramètre sortfield.Valeurs possibles : ASC - (par défaut) croissant ;DESC - décroissant. |
| startSearch | boolean | Le paramètre search comparera le début des champs, c'est-à-dire qu'il effectuera à la place une recherche LIKE "…%".Ignoré si searchWildcardsEnabled est défini sur true. |
Indicateurs d'origine des entités
Les méthodes get renvoient une propriété flags pour les entités liées à la découverte de bas niveau (règle LLD/prototype de règle LLD, élément/prototype d'élément, etc.). Cette propriété est utile pour indiquer si l'entité a été découverte ou non, car la modification des entités découvertes est limitée.
La propriété flags renvoie un résultat basé sur une combinaison (opération « + ») de ces valeurs :
| Value | Description |
|---|---|
| 0 | Entité de base (élément, déclencheur, graphe, hôte) |
| 1 | Règle de découverte de bas niveau |
| 2 | Tout prototype (prototype d'élément, prototype de déclencheur, prototype de règle LLD, etc.) |
| 4 | Entité découverte (élément, déclencheur, graphe, hôte, règle LLD découverts) |
La valeur combinée renvoyée par la propriété flags peut être :
| Value | Combination of | Description |
|---|---|---|
| 0 | 0 | Entité simple (élément, déclencheur, graphe, hôte). |
| 2 | 2 | Prototype d'entité (prototype d'élément, prototype de déclencheur, etc.). |
| 6 | 2+4 | Élément, déclencheur, graphe, hôte découverts (convertis à partir d'un prototype). |
| 1 | 1 | Règle de découverte de bas niveau. |
| 3 | 1+2 | Prototype de règle de découverte de bas niveau. |
| 5 | 1+4 | Règle de découverte de bas niveau découverte (convertie à partir d'un prototype). |
| 7 | 1+2+4 | Prototype de règle de découverte de bas niveau découvert. |
Exemples
Vérification des permissions de l'utilisateur
L'utilisateur a-t-il la permission d'écrire sur les hôtes dont les noms commencent 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
},
"id": 1
}Réponse :
{
"jsonrpc": "2.0",
"result": "0",
"id": 1
}Un résultat égal à zéro signifie qu'aucun hôte ne dispose de permissions de lecture/écriture.
Comptage des non-correspondances
Comptez le nombre d'hôtes dont les noms ne contiennent pas la sous-chaîne "ubuntu"
{
"jsonrpc": "2.0",
"method": "host.get",
"params": {
"countOutput": true,
"search": {
"host": "ubuntu"
},
"excludeSearch": true
},
"id": 1
}Réponse :
{
"jsonrpc": "2.0",
"result": "44",
"id": 1
}Recherche d'hôtes à l'aide de caractères génériques
Recherchez les hôtes dont le nom contient le mot "server" et qui ont des ports d'interface "10050" ou "10071". Triez le résultat par nom d'hôte dans l'ordre décroissant et limitez-le à 5 hôtes.
{
"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
},
"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 forme de 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
},
"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
}