取得最佳成效的最佳做法

在使用 Google 文档 API 时，您应遵循几个原则。 其中包括：

  • 反向修改，提高效率
  • 规划协作
  • 使用 WriteControl 字段
  • 将标签页纳入考量

以下部分介绍了这些原则。

反向修改，提高效率

在对 documents.batchUpdate 方法，对请求进行排序， 索引位置的降序。这样就无需计算 索引因插入和删除而发生变化。

规划协作

预计文档状态会发生变化。在一个方法调用和另一个方法调用之间， 协作者可能会更新文档，如下图所示：

文档在方法调用之间的变化方式。

如果您的索引有误，这可能会导致错误。如果有多位用户修改同一个 文档，Google 文档会透明地处理这个问题。不过， 作为 API 客户端，您的应用必须对其进行管理即使您 进行文档协作时，一定要采取防御性编程方式， 确保文档状态保持一致。为了确保一致性 查看 WriteControl 部分。

使用 WriteControl 建立状态一致性

当您在读取并更新文档时，可以控制 使用 WriteControl documents.batchUpdate 方法中的字段。WriteControl 提供权限 以控制写入请求的执行方式。

以下是使用方式：

  1. 使用 documents.get 方法并保存 revisionId 来自返回的 documents 资源。
  2. 编写您的更新请求。
  3. 添加可选的 WriteControl 对象：
    1. requiredRevisionId 字段设置为 revisionId 应用写入请求的文档。如果文档已被修改 因为 API 读取请求，所以不会处理写入请求， 返回一个错误。
    2. targetRevisionId 字段设置为文档的 revisionId 写入请求。如果文档在 API 读取请求，写入请求的更改将应用于 协作者的更改。写入请求的结果包含 写入请求变更，而协作者则变更为新的 修改文档。Google 文档服务器负责 用于合并内容

如需查看如何使用 WriteControl 构建批量请求的示例，请参阅 这个批量请求示例。

将标签页纳入考量

一个文档可以包含多个制表符， 您需要在 API 请求中对请求进行特定处理。

请注意以下几点：

  1. 在includeTabsContenttrue documents.get 方法 检索文档中所有标签页中的内容。默认情况下，并非所有标签页 内容。
  2. 指定要应用各个 Request 的标签页的 ID 在documents.batchUpdate中将 方法。每个Request 提供一种方式，用于指定要应用更新的标签。默认情况下，如果 未指定标签页时，Request 多数情况下会应用到文档中的第一个标签页。请参阅 Request 秒 文档。