此页面由 Cloud Translation API 翻译。

提升性能

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

使用 gzip 进行压缩

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

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

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

使用部分资源

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

部分请求有以下两种类型：

部分响应：在此类请求中指定要包含在响应中的字段（使用 fields 请求参数）。
修补：在此类更新请求中只发送您想更改的字段（使用 PATCH HTTP 动词）。

如需详细了解如何发出部分请求，请参阅以下各部分内容。

部分响应

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

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

注意，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/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"
    }
  },
  ...
  ]
}

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

修补（部分更新）

在修改资源时，您也可以避免发送不必要的数据。如果您只想为您要更改的特定字段发送更新数据，请使用 HTTP PATCH 动词。本文所述的修补语义不同于采用 GData 实现的旧版部分更新方案，并且更简单。

下面的简短示例显示了如何使用修补最大限度地减少进行小的更新时需要发送的数据。

示例

本示例显示的是一个简单的修补请求，目的只是为了更新一个通用（虚构）“Demo” API 资源的标题。该资源还包含一条注释、一组特征、状态以及许多其他字段，但由于 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 状态代码以及更新后的资源的完整表示形式。由于修补请求中仅包含 title 字段，因此只有该值会与之前的值有所不同。

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

修补请求的语义

修补请求的正文中仅包含您要修改的资源字段。在指定字段时，您必须将其所属的任何父级对象也包括在内，就如部分响应中也会返回所属父级对象。您发送的已修改数据将合并到父对象（如果有）的数据中。

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

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

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

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

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

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. */
  }
}

直接构建修补请求

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

注意：您可以借助 "If-Match: *" HTTP 标头强制在使用 ETag 时完成修补。如果您采用这一方法，就无需在写入之前执行读取操作。

不过，在其他一些情况下，您可以直接构建修补请求，无需首先检索现有数据。例如，您可以轻松创建一个修补请求，用以将某个字段更新为新值或添加一个新字段。示例如下：

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 字段（如果已设置）会被移除。

处理修补请求的响应

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

修补请求的响应会返回资源的完整表示形式，除非您使用 fields 参数减少其返回的数据量。

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

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

如果您的防火墙不允许 HTTP PATCH 请求，则可使用 HTTP POST 请求，并将替换标头设为 PATCH，如下所示：

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

修补与更新之间的区别

在实际操作中，当为使用了 HTTP PUT 动词的更新请求发送数据时，您只需发送那些必需或可选字段；如果您发送服务器所设置的字段值，这些值将会被忽略。尽管这看起来好像是另一种执行部分更新的方法，但该方法有一些局限性。对于使用 HTTP PUT 动词的更新，如果您没有提供必需参数，则请求会失败；如果您没有提供可选参数，则请求会清除之前设置的数据。

出于以上原因，使用补丁程序是一个安全得多的选择。您只需为自己想要修改的字段提供数据；系统不会清除您省略的字段。此规则的唯一例外情况是存在重复的元素或数组之时：如果您省略所有重复的元素或数组，它们将会保持原样；如果您提供其中任何元素或数组，系统会将所有元素或数组替换为您提供的元素或数组。

批量请求

本文档介绍了如何对 API 调用进行批处理以减少客户端必须建立的 HTTP 连接数量。

本文档专门介绍了如何通过发送 HTTP 请求来发出批处理请求。如果您要使用某个 Google 客户端库来发出批处理请求，请参阅该客户端库的说明文档。

概览

客户端建立的每个 HTTP 连接都会产生一定的开销。Google Drive API 支持批处理，这样您的客户端就可以将多个 API 调用组合为一个 HTTP 请求。

在以下示例情况下，您可能需要使用批处理：

检索大量文件的元数据。
批量更新元数据或房源。
更改大量文件的权限，例如添加新用户或群组。
首次同步本地客户端数据或长时间处于离线状态时同步本地客户端数据。

在上述每种情况下，您都可以将这些调用组合成一个 HTTP 请求，而不是单独发送每个调用。请注意，所有内部请求都必须发送到同一 Google API。

单个批量请求最多可以包含 100 次调用。如果必须进行更多次调用，请使用多个批量请求。

注意：Google 云端硬盘 API 的批处理系统使用的语法与 OData 批处理系统相同，但语义有所不同。

其他限制包括：

调用超过 100 次的批量请求可能会导致错误。
每个内部请求的网址长度不得超过 8,000 个字符。
Google 云端硬盘不支持对媒体文件执行批量操作，无论是上传、下载还是导出文件。

批量详情

批量请求就是将多个 API 调用进行合并而形成的一个 HTTP 请求，您可以将此请求发送到 API 发现文档中指定的 batchPath。默认路径为 /batch/api_name/api_version。本部分详细介绍了批处理语法，随后还会提供一个示例。

注意：一组一起进行批处理的 n 个请求将按 n 个请求（而非一个请求）计入用量限额。在处理之前，系统会将批量请求拆分为一组请求。

批量请求的格式

批量请求是一个包含多个 Google Drive API 调用的标准 HTTP 请求，使用 multipart/mixed 内容类型。在此主 HTTP 请求中，每个部分都包含一个内嵌的 HTTP 请求。

各个部分都以其自身的 Content-Type: application/http 标头开头。您还可以选择添加一个 Content-ID 标头。不过，每个部分的标头仅用于标记该部分的开头，而与嵌套请求无关。在服务器将批量请求拆分为多个单独请求之后，每个部分的标头就会被忽略。

各个部分的正文是一个完整的 HTTP 请求，各自有专用的动词、网址、标头和正文。此 HTTP 请求必须仅包含网址的路径部分；不允许在批量请求中使用完整的网址。

外部批量请求的 HTTP 标头应用于批次中的每个请求，但 Content-Type 之类的 Content- 标头除外。如果您在外部请求和个别调用中都指定了特定的 HTTP 标头，则个别调用标头的值将替换外部批量请求标头的值。另请注意，单个调用的标头仅应用于该调用本身。

例如，如果您为特定调用提供了 Authorization 标头，则该标头仅应用于该调用。如果您为外部请求提供了 Authorization 标头，则该标头将应用于所有的单个调用，除非单个调用将其替换为自身的 Authorization 标头。

当服务器收到批处理请求时，会将外部请求的查询参数和标头（如果适用）应用于各部分，然后将各部分视作单独的 HTTP 请求进行处理。

对批量请求的响应

服务器的响应是一个标准的 HTTP 响应，使用 multipart/mixed 内容类型；其中的每个部分分别是对批量请求中一个请求的响应，且顺序与这些请求相同。

和请求中的各部分一样，响应中的各部分都包含一个完整的 HTTP 响应，其中包括状态代码、标头和正文。此外，和请求中的各部分一样，响应中的各部分均以 Content-Type 标头为前缀，用于标记各部分的开头。

如果请求的某个特定部分具有 Content-ID 标头，则响应的对应部分也会有相同的 Content-ID 标头，其格式为在原始值前面加上 response- 字符串，如下例所示。

注意：服务器可能会以任何顺序执行您的调用，因此不要预期这些调用将会以您指定的顺序执行。如果要确保两个调用以指定顺序执行，就不能在单个请求中发送这两个调用。正确的做法是，先单独发送第一个调用，等收到其响应之后再发送第二个。

示例

以下示例展示了如何使用 Google Drive API 进行批处理。

批量请求示例

POST https://www.googleapis.com/batch/drive/v3 Accept-Encoding: gzip User-Agent: Google-HTTP-Java-Client/1.20.0 (gzip) Content-Type: multipart/mixed; boundary=END_OF_PART Content-Length: 963

--END_OF_PART Content-Length: 337 Content-Type: application/http content-id: 1 content-transfer-encoding: binary

POST https://www.googleapis.com/drive/v3/files/fileId/permissions?fields=id Authorization: Bearer authorization_token Content-Length: 70 Content-Type: application/json; charset=UTF-8

{ "emailAddress":"example@appsrocks.com", "role":"writer", "type":"user" } --END_OF_PART Content-Length: 353 Content-Type: application/http content-id: 2 content-transfer-encoding: binary

POST https://www.googleapis.com/drive/v3/files/fileId/permissions?fields=id&sendNotificationEmail=false Authorization: Bearer authorization_token Content-Length: 58 Content-Type: application/json; charset=UTF-8

{ "domain":"appsrocks.com", "role":"reader", "type":"domain" } --END_OF_PART--

批量响应示例

此部分是对上一部分中的示例请求的响应。

HTTP/1.1 200 OK Alt-Svc: quic=":443"; p="1"; ma=604800 Server: GSE Alternate-Protocol: 443:quic,p=1 X-Frame-Options: SAMEORIGIN Content-Encoding: gzip X-XSS-Protection: 1; mode=block Content-Type: multipart/mixed; boundary=batch_6VIxXCQbJoQ_AATxy_GgFUk Transfer-Encoding: chunked X-Content-Type-Options: nosniff Date: Fri, 13 Nov 2015 19:28:59 GMT Cache-Control: private, max-age=0 Vary: X-Origin Vary: Origin Expires: Fri, 13 Nov 2015 19:28:59 GMT

--batch_6VIxXCQbJoQ_AATxy_GgFUk Content-Type: application/http Content-ID: response-1

HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Date: Fri, 13 Nov 2015 19:28:59 GMT Expires: Fri, 13 Nov 2015 19:28:59 GMT Cache-Control: private, max-age=0 Content-Length: 35

{ "id": "12218244892818058021i" }

--batch_6VIxXCQbJoQ_AATxy_GgFUk Content-Type: application/http Content-ID: response-2

HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Date: Fri, 13 Nov 2015 19:28:59 GMT Expires: Fri, 13 Nov 2015 19:28:59 GMT Cache-Control: private, max-age=0 Content-Length: 35

{ "id": "04109509152946699072k" }

--batch_6VIxXCQbJoQ_AATxy_GgFUk--

从请求中返回特定字段

默认情况下，服务器会返回一组特定于所用方法的默认资源字段。例如，files.list 方法可能只会返回 id、name 和 mimeType。这些字段可能不是您所需的确切字段。如果您需要返回其他字段，请参阅返回文件的特定字段。