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

Le paramètre de la requête de début est pris en charge par les mêmes commandes que le paramètre de limite. Il fournit l'index de départ utilisé pour démarrer les données renvoyées. Pour les ressources prenant en charge les valeurs d'heure, l'index peut être une valeur d'heure, par exemple "20130531T01:13:58".

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.

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.