Paramètres de requête

Certaines demandes utiliseront des paramètres de requête facultatifs qui modifieront ou amélioreront les données renvoyées. Pour plus d'informations, reportez-vous à la documentation de chaque ressource. Tous les paramètres de requête ne sont pas pris en charge par toutes les ressources. Cette section présente uniquement les paramètres de requête courants utilisés lorsqu'une ressource n'implémente pas le paramètre de requête spécifié.

Table 2  Paramètres de requête courants

Paramètre Description props=true Enumération des métadonnées de la propriété pour une ressource (la valeur par défaut est false) limit=n Limitation du nombre d'éléments de la liste renvoyés start=n Numéro d'index (ou heure) défini pour démarrer le renvoi de données d'élément depth=n Numéro d'index qui indique le niveau de détail des données renvoyées match_Property-Name=Value Répertorie les données correspondant à la valeur et au nom de propriété indiqués

Paramètre de requête : props

Le paramètre de requête props peut être utilisé sur des commandes GET, POST, PUT pour permettre aux utilisateurs finaux d'accéder aux métadonnées. Pour demander cette fonctionnalité, l'utilisateur final attribue la valeur true à ce paramètre. Pour les opérations GET et PUT, l'objet JSON renvoyé contient les données requises avec les métadonnées de la liste de propriétés . Pour POST, seules les métadonnées sont renvoyées pour aider l'utilisateur à créer une ressource correctement.

Table 3  Valeurs des métadonnées de la propriété

Propriété Description name Nom de la propriété label Description de la propriété immutable Indicateur de l'impossibilité de modifier une propriété type Type de propriété : String, Integer, Boolean... choices Groupe de valeurs disponibles pour les propriétés énumérées

Paramètre de requête : limit

Vous pouvez utiliser la requête de limite sur de nombreuses commandes GET renvoyant un grand nombre d'éléments afin de limiter le nombre maximum d'éléments renvoyés.

Paramètre de requête : start

Pour les ressources prenant en charge les valeurs d'heure, l'index peut être une valeur d'heure, par exemple "20170531T01:13:58", et doit être exprimé au format UTC.

Paramètre de requête : depth

Le paramètre de requête depth s'utilise avec la commande GET pour extraire une liste de ressources. Il est utilisé pour spécifier le niveau de détail de la liste renvoyée. Plus le nombre définissant depth est élevé, plus le nombre de détails affichés sera important. Par exemple :

• /api/...?depth=0 - Renvoie les propriétés de noeud et uniquement les noms des enfants.

• /api/...?depth=1 - Renvoie les propriétés de noeud, les noms et propriétés des enfants, et uniquement les noms des petits-enfants.

• /api/...?depth=2 - Renvoie les propriétés de noeud, les noms et propriétés des enfants, et la sortie depth=0 des petits-enfants.

Exemple de demande effectuée à l'aide des paramètres de requête depth :

GET /api/user/v1/users?depth=2 HTTP/1.1                    
Host: zfs-storage.example.com
X-Auth-User: root
X-Auth-Key: letmein-xxx

Dans cet exemple, une liste d'utilisateurs sera renvoyée avec des détails jusqu'au niveau depth=2.

Exemple de réponse :

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1558
X-Zfssa-Access-Api: 1.0

{"users":
    [{
	"name": "root",
	"properties": {
		"logname": "root",
		"fullname": "Super-User",
		"initial_password": "DummyPassword",
		"require_annotation": false
	},
	"children": [{
		"name": "preferences",
		"properties": {
			"locale": "C",
			"login_screen": "status/dashboard",
			"session_timeout": 15,
			"advanced_analytics": false
		},
		"children": [{
			"name": "keys",
			"properties": {},
			"children": [],
			"list": []
		}],
		"list": []
	}],
	"list": [],
	"href": "/api/user/v1/users/root"
    },
    {
	"name": "tom",
	"properties": {
		"logname": "tom",
		"fullname": "Tommy",
		"initial_password": "DummyPassword",
		"require_annotation": false,
		"roles": ["basic"],
		"kiosk_mode": false,
		"kiosk_screen": "status/dashboard"
	},
	"children": [{
		"name": "exceptions",
		"properties": {},
		"children": [],
		"list": [{
			"name": "auth-000",
			"properties": {
				"scope": "stat",
				"drilldowns": "*",
				"allow_create": false,
				"allow_read": true
			},
			"children": [],
			"list": []
			},
			{
			"name": "auth-001",
			"properties": {
				"scope": "ad",
				"name": "*",
				"allow_domain": true,
				"allow_workgroup": false
			},
			"children": [],
			"list": []
		}]
	}, {
		"name": "preferences",
		"properties": {
			"locale": "C",
			"login_screen": "status/dashboard",
			"session_timeout": 15,
			"advanced_analytics": false
		},
		"children": [{
			"name": "keys",
			"properties": {},
			"children": [],
			"list": ["key-000"]
		}],
		"list": []
	}],
	"list": [],
	"href": "/api/user/v1/users/tom"
    }]
}

Paramètre de requête : match

Le paramètre de requête match_Property-Name=Value peut être utilisé avec la commande GET pour extraire une liste de ressources. Il renverra une liste de données correspondant au nom et à la valeur de propriété indiqués. Par exemple :

• /api/...?depth=0&match_kiosk_mode=true - Renvoie une liste filtrée lorsque kiosk_mode est défini sur true avec les noms des enfants.

• /api/...?depth=1&match_kiosk_mode=true - Renvoie une liste filtrée lorsque kiosk_mode est défini sur true avec des détails jusqu'à depth=1.

• /api/...?depth=2&match_Fullname='Super*'&kiosk_mode=true - Renvoie une liste filtrée pour fullname contenant Super et kiosk_mode défini sur true avec des détails jusqu'à depth=2.