WordPress REST API手册(四 | 1):全局参数

API 包含许多全局参数(也称为“元参数”),这些参数控制 API 如何处理请求/响应处理。它们在实际资源本身之上的一层运行,并且可用于所有资源。

_fields

像 Post 这样的 REST 资源包含大量数据:内容、标题和作者 ID 等基本信息,还包括已注册的元数据和字段、媒体信息以及指向其他资源的链接。您的应用程序可能不需要每个请求的所有这些信息。

要指示 WordPress 在响应中仅返回字段的子集,您可以使用_fields查询参数。例如,如果您正在构建一个存档视图,并且只需要 ID、标题、永久链接、作者和摘录来获取帖子集合,则可以将响应限制为仅具有以下字段查询的那些属性:

/wp/v2/posts?_fields=author,id,excerpt,title,link

您也可以使用查询参数数组语法而不是逗号分隔的列表来提供相同的列表:

/wp/v2/posts?_fields[]=author&_fields[]=id&_fields[]=excerpt&_fields[]=title&_fields[]=link

提供时_fields,WordPress 将在生成响应对象时跳过不需要的字段,避免潜在的昂贵的内部计算或查询您不需要的数据。这也意味着从 REST API 返回的 JSON 对象将更小,下载所需的时间更少,在客户端设备上解析的时间也更少。

仔细设计您的查询以仅从每个资源中提取所需的属性,以使您的应用程序更快地使用和更高效地运行。

从 WordPress 5.3 开始,该_fields参数支持嵌套属性。如果您注册了许多元键,这将很有用,允许您仅请求一个已注册元属性的值:

?_fields=meta.one-of-many-keys

只返回带有键的元值one-of-many-keys,其他的将被排除。

您还可以在复杂的元对象中请求特定的深层嵌套属性:

?_fields=meta.key_name.nested_prop.deeply_nested_prop,meta.key_name.other_nested_prop

_embed

大多数资源都包含相关资源的链接。例如,帖子可以链接到父帖子或帖子的评论。为了减少所需的 HTTP 请求数量,客户端可能希望获取资源以及链接的资源。该_embed参数向服务器指示响应应包括这些嵌入式资源。

_embed如果在查询字符串(GET 参数)中传递参数,则启用嵌入模式。此参数不需要值(即?_embed有效),但是如果客户端库需要,可以将“1”作为值传递。

从 WordPress 5.4 开始,可以通过将链接关系名称列表传递给_embed参数来限制要嵌入的资源。例如,/wp/v2/posts?_embed=author,wp:term将仅嵌入帖子的作者和与帖子关联的术语列表。

嵌入模式下的资源将在包含链接资源_embedded的键旁边包含一个附加键。_links只有embeddable参数设置为的链接true才会被嵌入。

有关链接和嵌入的更多信息,请参阅链接和嵌入页面。

_method(或X-HTTP-Method-Override标题)

某些服务器和客户端无法正确处理 API 使用的某些 HTTP 方法。例如,所有对资源的删除请求都使用该DELETE方法,但有些客户端不提供发送该方法的能力。

为了确保与这些服务器和客户端的兼容性,API 支持方法覆盖。这可以通过_method参数或X-HTTP-Method-Override标头传递,并将值设置为要使用的 HTTP 方法。

POSTto/wp-json/wp/v2/posts/42?_method=DELETE将被转换为DELETE路由wp/v2/posts/42

同样,以下 POST 请求将变为 DELETE:

POST /wp-json/wp/v2/posts/42 HTTP/1.1
Host: example.com
X-HTTP-Method-Override: DELETE

_envelope

与 类似_method,一些服务器、客户端和代理不支持访问完整的响应数据。API 支持传递_envelope参数,该参数发送正文中的所有响应数据,包括标头和状态代码。

_envelope如果在查询字符串(GET 参数)中传递参数,则启用信封模式。此参数不需要值(即?_envelope有效),但如果客户端库需要,可以将“1”作为值传递。

封装的响应包括一个“假”的 HTTP 200 响应代码,没有额外的标头(除了 Content-Type),应该确保响应正确地通过中介。

例如,给定以下对 a GETto的响应wp/v2/users/me

HTTP/1.1 302 Found
Location: http://example.com/wp-json/wp/v2/users/42
 
{
  "id": 42,
  ...
}

等效的封装响应(带有GETto wp/v2/users/me?_envelope)将是:

HTTP/1.1 200 OK
 
{
  "status": 302,
  "headers": {
    "Location": "http://example.com/wp-json/wp/v2/users/42"
  },
  "body": {
    "id": 42
  }
}

_jsonp

API 本身支持JSONP响应,以允许对旧版浏览器和客户端的跨域请求。此参数采用 JavaScript 回调函数,该函数将附加到数据中。然后可以通过<script>标签加载此 URL。

回调函数可以包含任何字母数字、_(下划线)或.(句点)字符。包含无效字符的回调将收到 HTTP 400 错误响应,并且不会调用回调。

例如:

<script>
function receiveData( data ) {
  // Do something with the data here.
  // For demonstration purposes, we'll simply log it.
  console.log( data );
}
</script>
<script src="https://example.com/wp-json/?_jsonp=receiveData"></script>

《WordPress REST API手册》完整目录:

THE END
评论 抢沙发
头像
欢迎您留下宝贵的见解!
提交
头像

昵称

取消
昵称表情代码图片