4.8.3. “fields”查询参数

“fields”查询参数用于可选地标识要在GET方法中检索的目标资源内的数据节点。客户端可以使用此参数来检索资源中所有节点的子集。

服务器将返回一个代表目标资源的消息体，其后代节点被修剪为“fields-expr”值中指定的值。服务器不会返回一组单独的子资源。

“fields”查询参数的值与以下规则匹配：

fields-expr = path "(" fields-expr ")" / path ";" fields-expr / path
path = api-identifier [ "/" path ]

第3.5.3.1节定义了“api-identifier”。

“;”用于选择多个节点。例如，要仅检索专辑的“genre”和“year”，请使用“fields=genre;year”。

圆括号用于指定节点的子选择器。请注意，“path”字段和左括号字符“(（”之间没有路径分隔符“/”。

例如，假设目标资源是“album”列表。要仅检索相册中“admin”容器的“label”和“catalogue-number”，请使用“fields=admin(label;catalogue-number)”。

在路径中使用“/”来检索节点的子节点。例如，要仅检索相册的“label”，请使用“fields=admin/label”。

此参数仅适用于API，数据存储区和数据资源上的GET方法。如果用于其他方法或资源类型，则返回“400 Bad Request”状态行。

如果在9.3节中定义的“capability”叶子列表中列出了“fields”查询参数URI，则服务器支持“fields”参数。