Parámetros de la consulta

Algunas solicitudes tomarán parámetros de consulta adicionales que modificarán o mejorarán los datos devueltos. Consulte la documentación para cada recurso para obtener detalles. No todos los recursos admitirán todos los parámetros de cada consulta. Esta sección solo documenta los parámetros de consulta que se usarán cuando un recurso implemente el parámetro de consulta especificado.

Tabla 2  Parámetros de consulta especificados:

Parámetro Descripción props=true Detallar los metadatos de la propiedad de un recurso (el valor por defecto es "false"). limit=n Limitar el número de elementos de lista devueltos. start=n Número de índice (o tiempo) utilizado para iniciar los datos de elementos devueltos. depth=n Número de índice que especifica el nivel de detalle de los datos devueltos. match_Property-Name=Value Muestra los datos que coinciden con el nombre y el valor de propiedad especificados.

Parámetro de consulta: props

El parámetro de consulta props se puede usar en los comandos GET, POST y PUT para permitir a los usuarios finales acceder a los metadatos. Para solicitar esta capacidad, el usuario final configura el parámetro de consulta props con el valor true. Para las operaciones GET y PUT, el objeto JSON devuelto incluye los datos requeridos con los metadatos de la lista de propiedades. Para POST, se devuelven solo los metadatos para ayudar al usuario a crear un recurso correctamente.

Tabla 3  Valores de metadatos de propiedad

Propiedad Descripción name Nombre de propiedad label Descripción de la propiedad immutable Indicador que muestra que la propiedad no se puede modificar type Tipo de propiedad: String, Integer, Boolean... choices Para propiedades enumeradas, una matriz de valores disponibles

Parámetro de consulta: limit

La consulta limit se puede usar en varios comandos GET que devuelven un gran número de elementos a fin de limitar el número máximo de elementos devueltos.

Parámetro de consulta: start

Para los recursos que admiten valores de tiempo, el índice puede ser un valor de tiempo, como "20170531T01:13:58" y se debe expresar en hora UTC.

Parámetro de consulta: depth

El parámetro de consulta depth se puede usar con el comando GET para recuperar una lista de recursos. Se lo usa para especificar el nivel de detalle para la lista devuelta. Cuanto mayor sea la profundidad, mayor será el detalle devuelto. Por ejemplo:

• /api/...?depth=0: devuelve propiedades de nodos y solo nombres de elementos secundarios.

• /api/...?depth=1: devuelve propiedades de nodos, nombres y propiedades de elementos secundarios, y solo nombres de elementos terciarios.

• /api/...?depth=2: devuelve propiedades de nodos, nombres y propiedades de elementos secundarios y la salida de depth=0 de elementos terciarios.

Ejemplo de solicitud para parámetros de consulta 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

En este ejemplo, se devolverá una lista de usuarios con detalles hasta una profundidad depth=2.

Ejemplo de respuesta:

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"
    }]
}

Parámetro de consulta: match

El parámetro de consulta match_Property-Name=Value se puede usar con el comando GET para recuperar una lista de recursos. Devuelve una lista de datos que coinciden con el nombre y el valor de propiedad especificados. Por ejemplo:

• /api/...?depth=0&match_kiosk_mode=true: devuelve una lista filtrada para kiosk_mode true con nombres de elementos secundarios.

• /api/...?depth=1&match_kiosk_mode=true: devuelve una lista filtrada para kiosk_mode true con detalles hasta depth=1.

• /api/...?depth=2&match_Fullname='Super*'&kiosk_mode=true: devuelve una lista filtrada para fullname que contiene Super y kiosk_mode con el valor true con detalles hasta depth=2.