查询参数

一些请求将使用可选查询参数，这些参数将修改或增强返回的数据。有关详细信息，请参见各个资源的文档。不是每个资源都支持所有查询参数。本节仅记录当资源实施指定的查询参数时将使用的常用查询参数。

表 2  常用查询参数

参数 描述 props=true 列出资源的属性元数据（默认值为 false） limit=n 限制返回的列表元素数量 start=n 用作返回的元素数据开头的索引号（或时间） depth=n 索引号指定返回数据的详细程度 match_Property-Name=Value 列出与指定属性名称和值匹配的数据

查询参数：props

props 查询参数可用于 GET、POST 或 PUT 命令，以便最终用户访问元数据。最终用户通过将查询参数 props 设置为 true 来请求此功能。对于 GET 和 PUT 操作，返回的 JSON 对象将包含所需的数据以及属性的元数据列表。对于 POST，将仅返回元数据以帮助用户正确创建资源。

表 3  属性元数据值

属性 描述 name 属性名称 label 属性描述 immutable 此标志指示属性不可修改 type 属性类型： String, Integer, Boolean... choices 对于枚举属性，则为可用值的数组

查询参数：limit

限制查询可用于返回大量元素的众多 GET 命令，以限制返回元素的最大数量。

查询参数：start

支持限制参数的命令也支持开始查询参数。此开始查询参数提供用作返回数据的开头的起始索引。对于支持时间值的资源，此索引可能是一个时间值，例如 "20130531T01:13:58"。

查询参数：depth

depth 查询参数可用于检索资源列表的 GET 命令。该参数用于指定返回列表的详细程度。depth 的数值越大，返回的信息越详细。

使用查询参数 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

在此示例中，将按 depth=2 这一详细程度返回用户列表。

响应示例：

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

查询参数：match

match_Property-Name=Value 可用于检索资源列表的 GET 命令。将返回与指定属性名称和值匹配的数据列表。