全局参数
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 方法。
警报:
客户端应该只发送带有 POST 请求的方法覆盖参数或标头。对 GET 请求使用方法覆盖可能会导致请求被错误地缓存。
to将POST
被/wp-json/wp/v2/posts/42?_method=DELETE
转换为DELETE
towp/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 GET
to的响应wp/v2/users/me
:
HTTP/1.1 302 Found
Location: http://example.com/wp-json/wp/v2/users/42
{
"id": 42,
...
}
等效的包络响应(带有GET
to 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 回调函数,该函数将添加到数据之前。然后可以通过标签加载此 URL <script>
。
回调函数可以包含任何字母数字、_
(下划线)或.
(句点)字符。包含无效字符的回调将收到 HTTP 400 错误响应,并且不会调用回调。
笔记:
现代浏览器可以使用跨域资源共享 (CORS)预检请求进行跨域请求,但 JSONP 可用于确保支持所有浏览器。
- 浏览器支持
- 关于 CORS 的 MDN 文章
例如:
<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>