查询参数

语言：

一些请求可以采用可选的查询参数，这些参数选择要返回或操作哪些数据。本节介绍了可以由多种类型的资源使用的查询参数。请参见每种资源的文档，了解特定于该资源的任何查询参数，以及本节中介绍的查询参数的特殊用途。

表 2 常用查询参数

参数	说明
`props=true`	列出资源的属性元数据。默认值为 `false`。
`start=index`	指定在指定的时间或对象 ID 之后要返回的最早数据或对象。
`end=index`	指定在指定的时间或对象 ID 之前要返回的最新数据或对象。
`limit=n`	返回不超过 `n` 个列表元素。
`depth=n`	指定返回数据的详细程度。
`match_property-name=value`	返回其指定属性等于指定值的列表对象。

查询参数：props

props 查询参数显示属性元数据值。在将 props=true 用于可能会更改数据或创建新数据的操作时，将显示属性和元数据，并且不会执行操作。这使您能够显示当前数据值，这些数据值可以帮助您修改或创建资源。

表 3 属性元数据值

属性	说明
`name`	属性名称
`label`	属性说明
`immutable`	此标志指示属性不可修改
`type`	属性类型，例如 String、Integer、Boolean 或 ChooseOne
`choices`	对于枚举属性，则为可用值的数组

查询参数：start

start 查询参数可以是对象索引编号或时间。

指定对象索引编号将返回一个列表，此列表中包括由该索引选择的对象，以及在创建指定的对象之后创建的最早对象。
指定 UTC 时间将返回在指定时间或其后创建的最早对象或数据的列表。某些资源不支持 start 查询参数的时间值。

时间值必须以下表中所示格式的 UTC 时间表示。

服务版本	时间值格式	时间值示例
`v1` 路径	`%Y%m%dT%H:%M:%SZ`	`20200723T14:11:49`
`v2` 路径	`%Y-%m-%dT%H:%M:%SZ`	`2020-07-23T14:11:49Z`

有关使用 start 查询参数的示例，请参见以下几节：

查询参数：end

end 查询参数可以是对象索引编号或时间。

指定对象索引编号将返回一个列表，此列表中包括由该索引选择的对象，以及在创建指定的对象之前创建的最新对象。
指定 UTC 时间将返回在指定时间或其前创建的最新对象或数据的列表。

时间值必须以 %Y-%m-%dT%H:%M:%SZ 格式的 UTC 时间表示。

有关使用 end 查询参数的示例，请参见列出云备份。

查询参数：limit

limit 查询参数指定要返回的最大元素数量。

如果既未指定 start 又未指定 end，则 limit=n 返回 n 个最新的元素。

查询参数：depth

depth 查询参数指定所返回资源列表的详细程度，depth 值越大，越详细，如下表中所示。

depth 值	在列表中返回的信息
`depth=0`	节点的属性和子节点的名称
`depth=1`	节点的属性、子节点的名称和属性以及孙节点的名称
`depth=2`	节点的属性、子节点的名称和属性以及孙节点的 `depth=0` 输出

注 - 使用 /api/log/v{1|2} 列出日志或者使用 /api/storage/v{1|2} 列出池、项目、文件系统或 LUN 时不支持 depth 查询参数。

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

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

响应示例：

为简洁起见，省略了其他用户。

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

{
  "users": [
    {
      "name": "root",
...
    },
    {
      "name": "firstlast",
      "properties": {
        "logname": "firstlast",
        "type": "directory",
        "uid": uid,
        "fullname": "First Last",
        "require_annotation": false,
        "roles": [
          "basic"
        ],
        "kiosk_mode": false,
        "kiosk_screen": "status/dashboard"
      },
      "children": [
        {
          "name": "exceptions",
          "properties": {},
          "children": [],
          "list": [
            {
              "name": "auth-000",
              "properties": {
                "scope": "ad",
                "name": "*",
                "allow_domain": true,
                "allow_workgroup": false
              },
              "children": [],
              "list": []
            },
            {
              "name": "auth-001",
              "properties": {
                "scope": "alert",
                "allow_configure": true,
                "allow_post": true
              },
              "children": [],
              "list": []
            }
          ]
        },
        {
          "name": "preferences",
          "properties": {
            "locale": "C",
            "login_screen": "configuration/preferences",
            "session_timeout": 15,
            "cli_idle_timeout": "infinite",
            "advanced_analytics": false
          },
          "children": [
            {
              "name": "keys",
              "properties": {},
              "children": [],
              "list": []
            },
            {
              "name": "tokens",
              "properties": {},
              "children": [],
              "list": []
            }
          ],
          "list": []
        }
      ],
      "list": [],
      "href": "/api/user/v1/users/firstlast"
    },
    {
...
    }
  ]
}

查询参数：match

matchproperty-name=value 查询参数返回其指定属性名称等于指定值的资源的列表。

以下示例返回其 kiosk_mode 属性的值为 true 的用户的列表：

match_kiosk_mode=true

以下示例返回其 roles 属性的值包含 super 而且 require_annotation 属性的值为 true 的用户列表：

match_roles='*super*'&match_require_annotation=true

注 - 使用 /api/log/v{1|2} 列出日志或者使用 /api/storage/v{1|2} 列出池、项目、文件系统或 LUN 时不支持 match_property-name=value 查询参数。