性能提示

本文介绍了一些您可以用来提高应用性能的技巧。在某些情况下,我们会使用其他 API 或通用 API 中的示例来说明所给出的建议,但其中蕴含的理念也同样适用于 Google Pay API for Passes。

使用 Gzip

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

要获得经过 Gzip 编码的响应,您必须执行以下两项操作:设置 Accept-Encoding 标头,并修改您的用户代理,使其包含字符串 gzip。下面是一个会启用 Gzip 压缩且格式正确的 HTTP 标头示例:

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

使用部分资源

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

部分请求 (partial request) 有以下两种类型:

  • 部分响应:一种请求,您在其中指定了响应中要包含的字段(使用 fields 请求参数)。
  • 补丁:一种更新请求,您在其中仅发送自己想要更改的字段(使用 PATCH HTTP 动词)。

如需详细了解如何发送部分请求,请参阅以下各个部分。

部分响应

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

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

请注意,fields 参数仅影响响应数据;它不会影响您需要发送的数据(如果有)。要减少修改资源所需发送的数据量,请使用 PATCH 请求。

示例

以下示例介绍了将 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/a/b 的数据对象会引发错误。在这种情况下,请改用 a/b 之类的 fields 规范。

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

    例如: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"
    }
  },
  ...
  ]
}

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

PATCH(部分更新)

在修改资源时,您也可以避免发送不必要的数据。如需仅为您要更改的特定字段发送更新数据,请使用 HTTP PATCH 动词。本文档中所述的 PATCH 语义与部分更新之前实现 GData 所用的语义不同,并且更为简单。

下面的简短示例介绍了如何使用 PATCH 最大程度地减少需要发送的数据,以进行一次小规模更新。

示例

本示例介绍了一个简单的 PATCH 请求,其目的只是为了更新通用(虚构)“Demo”API 资源的标题。该资源还包含一个 comment 字段、一组 characteristics 字段、一个 status 字段以及许多其他字段,但由于只需修改 title 字段,因此该请求仅会发送该字段:

PATCH https://www.googleapis.com/demo/v1/324
Authorization: Bearer your_auth_token
Content-Type: application/json

{
  "title": "New title"
}

响应:

200 OK
{
  "title": "New title",
  "comment": "First comment.",
  "characteristics": {
    "length": "short",
    "accuracy": "high",
    "followers": ["Jo", "Will"],
  },
  "status": "active",
  ...
}

服务器将返回 200 OK 状态代码,以及更新后的资源的完整表示形式。由于 PATCH 请求中仅包含 title 字段,因此只有该值会与之前不同。

注意:如果您将部分响应 fields 参数与 PATCH 请求结合使用,则可以进一步提高更新请求的效率。PATCH 请求只会减小请求的大小,而部分响应会减小响应的大小。因此,为了j减少两个方向发送的数据量,请将 PATCH 请求与 fields 参数结合使用。

PATCH 请求的语义

PATCH 请求的正文中仅包含您要修改的资源字段。指定字段时,必须将所属的全部父对象也包括在内,因为这些所属父对象会与部分响应一起返回。您发送的已修改数据将合并到父对象(如果有)的数据中。

  • 添加:要添加目前并不存在的字段,请指定这个新字段及其值。
  • 修改:要更改现有字段的值,请指定该字段并将其设为新值。
  • 删除:要删除字段,请指定该字段并将其设为 null。例如,"comment": null。此外,您还可以删除整个对象(如果该对象是可变更的),只需将其设为 null 即可。如果您使用的是 Java API 客户端库,请改用 Data.NULL_STRING;如需了解详情,请参阅 JSON null

关于数组的备注:包含数组的 PATCH 请求将使用您提供的数组替换现有数组。您不能逐个修改、添加或删除数组中的项目。

在读取-修改-写入周期中使用 PATCH

一种比较实用的做法是,先使用您要修改的数据检索部分响应。这对于使用 ETag 的资源来说尤为重要,因为您必须在 If-Match HTTP 标头中提供当前的 ETag 值,才能成功更新资源。获取数据之后,您就可以修改自己想要更改的值,并将已修改的部分表示形式与 PATCH 请求一起发回。以下示例假设 Demo 资源使用 ETag:

GET https://www.googleapis.com/demo/v1/324?fields=etag,title,comment,characteristics
Authorization: Bearer your_auth_token

以下是部分响应:

200 OK
{
  "etag": "ETagString"
  "title": "New title"
  "comment": "First comment.",
  "characteristics": {
    "length": "short",
    "level": "5",
    "followers": ["Jo", "Will"],
  }
}

以下 PATCH 请求基于该响应。如下所示,该请求还使用 fields 参数对 PATCH 响应中返回的数据进行限制:

PATCH https://www.googleapis.com/demo/v1/324?fields=etag,title,comment,characteristics
Authorization: Bearer your_auth_token
Content-Type: application/json
If-Match: "ETagString"
{
  "etag": "ETagString"
  "title": "",                  /* Clear the value of the title by setting it to the empty string. */
  "comment": null,              /* Delete the comment by replacing its value with null. */
  "characteristics": {
    "length": "short",
    "level": "10",              /* Modify the level value. */
    "followers": ["Jo", "Liz"], /* Replace the followers array to delete Will and add Liz. */
    "accuracy": "high"          /* Add a new characteristic. */
  },
}

服务器将返回 200 OK HTTP 状态代码,以及更新后的资源的部分表示形式:

200 OK
{
  "etag": "newETagString"
  "title": "",                 /* Title is cleared; deleted comment field is missing. */
  "characteristics": {
    "length": "short",
    "level": "10",             /* Value is updated.*/
    "followers": ["Jo" "Liz"], /* New follower Liz is present; deleted Will is missing. */
    "accuracy": "high"         /* New characteristic is present. */
  }
}

直接构建 PATCH 请求

对于某些 PATCH 请求,您需要以您之前检索过的数据为基础。例如,如果您要向数组中添加项目,并且不希望丢失任何现有的数组元素,则必须先获取现有的数据。同样,如果 API 使用 ETag,您需要将之前的 ETag 值与您的请求一起发送,才能成功更新资源。

注意:您可以借助 "If-Match: *" HTTP 标头强制在使用 ETag 的情况下执行 PATCH 请求。如果您执行了此操作,就无需在写入之前执行读取操作。

不过,对于其他情况,您可以直接构建 PATCH 请求,而无需先检索现有数据。例如,您可以轻松设置一个 PATCH 请求,以更新某个字段的值或添加一个新字段。示例如下:

PATCH https://www.googleapis.com/demo/v1/324?fields=comment,characteristics
Authorization: Bearer your_auth_token
Content-Type: application/json

{
  "comment": "A new comment",
  "characteristics": {
    "volume": "loud",
    "accuracy": null
  }
}

对于该请求,如果 comment 字段已有值,则新值会覆盖该值;否则,系统会将该字段设置为新值。同样,如果 volume 特征已有值,则该值会被覆盖;否则,系统会创建一个值。accuracy 字段(如果已设置)会被移除。

处理 PATCH 请求的响应

处理有效 PATCH 请求之后,API 会返回 200 OK HTTP 响应代码以及修改后的资源的完整表示形式。如果 API 使用了 ETag,则服务器会在成功处理 PATCH 请求后更新 ETag 值,就像执行 PUT 请求时一样。

PATCH 请求会返回资源的完整表示形式,除非您使用 fields 参数减少请求返回的数据量。

如果 PATCH 请求导致的新资源状态具有无效的语法或语义,则服务器会返回 400 Bad Request422 Unprocessable Entity HTTP 状态代码,并且资源状态会保持不变。例如,如果您尝试删除必填字段的值,服务器就会返回错误。

PATCH HTTP 动词不受支持时的备用表示法

如果您的防火墙不支持 HTTP PATCH 请求,请执行 HTTP POST 请求并将替换标头设为 PATCH,如下所示:

POST https://www.googleapis.com/...
X-HTTP-Method-Override: PATCH
...

patch 与 update 之间的区别

实际上,当您发送使用 HTTP PUT 动词的 update 请求的数据时,您只需发送必填或可选字段;如果您发送服务器所设置的字段的值,则这些值将会被忽略。虽然这似乎也是执行部分更新的一种方法,但会受到一些限制。对于使用 HTTP PUT 动词的 update 请求,如果您没有提供必需参数,则请求会失败;同样,如果您没有提供可选参数,则请求会清除之前设置的数据。

出于以上原因考虑,使用 patch 是更安全的选择。您只需为想要更改的字段提供数据即可,并且系统不会清除您省略的字段。此规则的唯一例外情况是存在重复的元素或数组时:如果您省略所有重复的元素或数组,这些元素或数组将会保持原样;如果您提供其中任何元素或数组,则系统会将所有元素或数组替换为您提供的元素或数组。