Oracle^® ZFS Storage Appliance RESTful API 指南，发行版 OS8.8.0

查询参数

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

表 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 属性类型，例如字符串、整数或布尔型。 choices 对于枚举属性，则为可用值的数组

查询参数：limit

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

查询参数：start

对于支持时间值的资源，index 可能是一个时间值（例如 20170531T01:13:58）并且必须以 UTC 时间表示。

查询参数：depth

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

• /api/...?depth=0－返回节点属性和子节点名称。

• /api/...?depth=1－返回节点的属性、子节点的名称和属性、孙节点的名称。

• /api/...?depth=2－返回节点的属性、子节点的名称和属性以及孙节点的 depth=0 输出。

使用查询参数 depth 的请求示例：

GET /api/user/v1/users?depth=2 HTTP/1.1                    
Host: zfs-storage.example.com
X-Auth-User: root
X-Auth-Key: password-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": "password",
		"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": "admin2",
	"properties": {
		"logname": "admin2",
		"fullname": "Administrator",
		"initial_password": "password",
		"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/admin2"
    }]
}

查询参数：match

match_property-name=value 查询参数可用于检索资源列表的 GET 命令。它将返回与指定属性名称和值匹配的数据列表。例如：

• /api/...?depth=0&match_kiosk_mode=true－如果 kiosk_mode 为 true，返回过滤后的列表，其中包含子节点的名称。

• /api/...?depth=1&match_kiosk_mode=true－如果 kiosk_mode 为 true，返回过滤后的列表，其中包含的详细信息具体到 depth=1。

• /api/...?depth=2&match_Fullname='Super*'&kiosk_mode=true－如果包含 Super 和 kiosk_mode 的 fullname 为 true，返回过滤后的列表，其中包含的详细信息具体到 depth=2。