API 使用提示

本文档介绍了可用来提高应用性能的方法和技巧。在某些情况下,我们会采用其他 API 或通用 API 中的示例来阐释所介绍的概念,不过,同样的概念也适用于 Google Search Console API。

使用 gzip 进行压缩

如需减少每个请求所需的带宽,您可以选择启用 gzip 压缩,这是一种既方便又简单的方法。虽然这种方法需要一些额外的 CPU 时间来对结果进行解压缩,但考虑到节约的网络费用,通常还是很值得的。

为了接收 gzip 编码的响应,您必须执行以下两项操作:设置 Accept-Encoding 标头,以及修改您的用户代理,使其包含字符串 gzip。下面提供了一个用于启用 gzip 压缩的格式正确的 HTTP 标头示例:

Accept-Encoding: gzip
User-Agent: my program (gzip)

使用部分资源

提高 API 调用性能的另一种方法是仅请求您感兴趣的那部分数据。这样可以避免应用传输、解析和存储不需要的字段,使应用可以更高效地利用网络、CPU 和内存等资源。

部分响应

默认情况下,处理完请求之后,服务器会发回资源的完整表示形式。为了提高性能,您可以要求服务器仅发送您真正需要的字段,从而只接收部分响应

如需请求部分响应,请使用 fields 请求参数来指定您希望返回的字段。对于返回响应数据的任何请求,您都可以使用此参数。

示例

以下示例显示的是将 fields 参数与通用(虚构)“Demo” API 结合使用的情况。

简单请求:下面的 HTTP GET 请求省略了 fields 参数,并且返回完整的资源。

https://www.googleapis.com/demo/v1

完整资源响应:完整资源数据包含以下字段以及其他许多字段(为简便起见,此处省略了那些字段)。

{
  "kind": "demo",
  ...
  "items": [
  {
    "title": "First title",
    "comment": "First comment.",
    "characteristics": {
      "length": "short",
      "accuracy": "high",
      "followers": ["Jo", "Will"],
    },
    "status": "active",
    ...
  },
  {
    "title": "Second title",
    "comment": "Second comment.",
    "characteristics": {
      "length": "long",
      "accuracy": "medium"
      "followers": [ ],
    },
    "status": "pending",
    ...
  },
  ...
  ]
}

对部分响应的请求:以下针对此同一资源的请求使用了 fields 参数,从而大幅减少了所返回的数据量。

https://www.googleapis.com/demo/v1?fields=kind,items(title,characteristics/length)

部分响应:服务器为响应上述请求而发回的响应只包含种类信息和一个简化的 items 数组,该数组中的每个项目只包含 HTML 标题和长度特征信息。

200 OK
{
  "kind": "demo",
  "items": [{
    "title": "First title",
    "characteristics": {
      "length": "short"
    }
  }, {
    "title": "Second title",
    "characteristics": {
      "length": "long"
    }
  },
  ...
  ]
}

请注意,该响应是一个只包括所选字段及其所属父对象的 JSON 对象。

接下来,我们将详细介绍如何设置 fields 参数格式,以及响应中会返回哪些确切内容。

“fields”参数语法摘要

fields 请求参数值的格式大致上基于 XPath 语法。以下内容对受支持的语法进行了总结。如需了解更多示例,请参阅下一部分。

  • 使用以英文逗号分隔的列表来选择多个字段。
  • 使用 a/b 选择嵌套在字段 a 内的字段 b;使用 a/b/c 选择嵌套在 b 内的字段 c

    例外:对于使用“data”封装容器的 API 响应(响应嵌套在 data 对象内,例如 data: { ... }),请勿在 fields 规范中包含“data”。在 fields 规范中加入 data 对象(如 data/a/b)会引发错误。请改用类似 a/bfields 规范。

  • 用圆括号“( )”将表达式括起来,使用子选择器请求数组或对象的一组特定子字段。

    例如:fields=items(id,author/email) 只会返回 items 数组中每个元素的项 ID 和作者的电子邮件地址。您还可以指定单个子字段,其中 fields=items(id) 等同于 fields=items/id

  • 如果需要,可在选择字段时使用通配符。

    例如:使用 fields=items/pagemap/* 即可选择 pagemap 中的所有对象。

使用 fields 参数的更多示例

下面的示例说明了 fields 参数值对响应有何影响。

注意:与所有查询参数值一样,fields 参数值也必须采用网址编码。为了便于阅读,本文中的示例省略了编码。

确定您希望返回的字段,或者进行字段选择
fields 请求参数值是一个以英文逗号分隔的字段列表,并且每个字段均是相对于响应的根来指定的。因此,如果您执行的是 list 操作,响应就是一个集合,其中通常包含一系列资源。如果您执行的是返回单一资源的操作,则字段是相对于该资源指定的。如果您选择的字段是一个数组(或是它的一部分),服务器便会返回数组中选定部分的所有元素。

下面提供了几个集合层面的示例:
示例 效果
items 返回 items 数组中的所有元素,包括每个元素中的所有字段,但不包括其他字段。
etag,items 同时返回 etag 字段和 items 数组中的所有元素。
items/title 仅返回 items 数组中所有元素的 title 字段。

每当返回嵌套字段时,响应中均会包含所属父级对象。父级字段不会包含其他任何子字段(除非已明确选择)。
context/facets/label 仅返回 facets 数组中所有成员的 label 字段,而该数组本身嵌套在 context 对象中。
items/pagemap/*/title 对于 items 数组中的每个元素,仅返回 pagemap 的所有子对象的 title 字段(如果存在)。

下面提供了几个资源级的示例:
示例 效果
title 返回所请求资源的 title 字段。
author/uri 返回所请求资源中 author 对象的 uri 子字段。
links/*/href
返回 links 的所有子对象的 href 字段。
使用“子选择”仅请求特定字段的某些部分。
默认情况下,如果您的请求指定具体字段,则服务器会完整地返回对象或数组元素。您可以指定一个仅包含特定子字段的响应。如下例所示,您可以使用“( )”子选择语法来实现此目的。
示例 效果
items(title,author/uri) 仅返回 items 数组中每个元素的 title 值和作者的 uri

处理部分响应

处理完含有 fields 查询参数的有效请求之后,服务器将发回一个 HTTP 200 OK 状态代码以及所请求的数据。如果 fields 查询参数出现错误或因其他原因而无效,服务器将返回一个 HTTP 400 Bad Request 状态代码以及一条错误消息,告知用户他们的字段选择出现了什么错误(例如 "Invalid field selection a/b")。

以下是上文简介部分所提到的部分响应的示例。该请求使用 fields 参数来指定要返回的字段。

https://www.googleapis.com/demo/v1?fields=kind,items(title,characteristics/length)

部分响应如下所示:

200 OK
{
  "kind": "demo",
  "items": [{
    "title": "First title",
    "characteristics": {
      "length": "short"
    }
  }, {
    "title": "Second title",
    "characteristics": {
      "length": "long"
    }
  },
  ...
  ]
}

注意:对于支持使用查询参数进行数据分页(例如 maxResultsnextPageToken)的 API,请使用这些参数将每个查询的结果缩减为易于管理的大小。否则,可能无法实现本可通过部分响应获得的性能提升。