提升性能

本文档介绍了可用来提高应用性能的方法和技巧。在某些情况下，我们会采用其他 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 参数仅影响响应数据；并不会影响您需要发送的数据（如有）。如需减少您在修改资源时发送的数据量，请使用修补请求。

示例

补丁（部分更新）

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

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

示例

处理修补请求的响应

处理有效修补请求之后，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--

从请求中返回特定字段

如果您未指定 fields 参数，服务器将返回一组特定于该方法的默认字段。例如，files.list 方法只会返回 kind、id、name 和 mimeType 字段。

返回的默认字段可能不是您需要的。如果您想指定要在响应中返回哪些字段，请使用 fields 系统参数。如需了解详情，请参阅返回特定字段。

对于 about、comments（不包括 delete）和 replies（不包括 delete）资源的所有方法，您必须设置 fields 参数。这些方法不会返回一组默认字段。