全局参数

最后更新于：2021-11-29 11:03:21

Global Parameters

API包括一些全局参数（也称为“元参数”），这些参数控制API如何处理请求/响应处理。这些在高于实际资源本身的一层运行，并且适用于所有资源。

_fields

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

要指示GeChiUI仅返回响应中字段的子集，您可以使用_fields查询参数。例如，如果您正在构建存档结构，并且只需要文章集合的ID、标题、永久链接、作者和摘录，则只能通过以下字段查询将响应限制为这些属性：

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

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

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

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

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

从GeChiUI 5.8起，_fields参数支持嵌套属性。如果您注册了许多元密钥，仅允许您为其中一个已注册的元属性请求值，这可能会很有用：

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

只返回键  one-of-many-keys  的meta值，其他将被排除。

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

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

_embed

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

如果在查询字符串（GET参数）中传递_embed参数，则启用嵌入结构。此参数不需要值（即?_embed有效），但如果客户端库需要，可以作为值传递“1”。

从GeChiUI 5.8起，可以通过将链接关系名称列表传递给_embed参数来限制要嵌入的资源。例如，/gc/v2/posts?_embed=author,gc:term将仅嵌入文章的作者和与文章相关的术语列表。

Resources in embed mode will contain an additional _embedded key next to the _links key containing the linked resources. Only links with the embeddable parameter set to true will be embedded.

嵌入结构下的资源将在包含链接资源的 _links 键旁边包含一个额外的 _embedded 键。仅嵌入 embeddable 参数设置为 true 的链接。

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

_method (or X-HTTP-Method-Override header)

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

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

警报：
客户端只应发送带有POST请求的方法重写参数或标头。将方法重写与GET请求一起使用可能会导致请求缓存不正确。

A POST to /gc-json/gc/v2/posts/42?_method=DELETE would be translated to a DELETE to the gc/v2/posts/42 route.

同样，以下POST请求将成为删除：

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

_envelope

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

如果在查询字符串（GET参数）中传递_envelope参数，则启用信封结构。此参数不需要值（即?_envelope有效），但如果客户端库需要，可以作为值传递“1”。

注意：
为了未来的兼容性，不应传递其他值。

包罗万象的响应包括一个“假”HTTP 200响应代码，没有额外的标头（内容类型除外），以确保响应正确通过中介。

例如，给定对 gc/v2/users/me 的GET 以下响应：

HTTP/1.1 302 Found
Location: http://example.com/gc-json/gc/v2/users/42

{
  "id": 42,
  ...
}

The equivalent enveloped response (with a GET to gc/v2/users/me?_envelope) would be:

HTTP/1.1 200 OK

{
  "status": 302,
  "headers": {
    "Location": "http://example.com/gc-json/gc/v2/users/42"
  },
  "body": {
    "id": 42
  }
}

_jsonp

API本机支持JSONP响应，以允许对传统浏览器和客户端进行跨域请求。此参数采用JavaScript回调函数，该函数将以数据为前缀。然后，可以通过<script>标签加载此URL。

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

注意：
现代浏览器可以使用跨源资源共享（CORS）飞行前请求处理跨域请求，但可以使用JSONP来确保所有浏览器的支持。

例如：

<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/gc-json/?_jsonp=receiveData"></script>