取得最佳成效的最佳做法

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

  • 从后往前编辑以提高效率
  • 规划协作
  • 使用 WriteControl 字段确保状态一致
  • 考虑标签页

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

从后往前编辑，提高效率

在对 documents.batchUpdate 方法的单次调用中，请按索引位置的降序对请求进行排序。这样，您就不必计算因插入和删除而导致的索引更改。

规划协作

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

文档在方法调用之间如何更改。

如果您的索引有误，就可能会导致错误。当多位用户使用界面编辑文档时，Google 文档会透明地处理这项工作。不过，作为 API 客户端，您的应用必须管理此问题。即使您不打算协同处理文档，也请务必采用防御性编程并确保文档状态保持一致。如需了解确保一致性的方法，请参阅 WriteControl 部分。

使用 WriteControl 建立状态一致性

在读取文档后再更新文档时，您可以使用 documents.batchUpdate 方法中的 WriteControl 字段控制如何处理竞争更改的行为。WriteControl 负责管理写入请求的执行方式。

具体使用方法如下：

  1. 使用 documents.get 方法获取文档，并保存从返回的 documents 资源中获取的 revisionId。
  2. 编写更新请求。
  3. 添加一个可选的 WriteControl 对象，并使用以下两个选项之一：
    1. requiredRevisionId 字段设置为要应用写入请求的文档的 revisionId。如果文档在 API 读取请求发出后发生了修改，系统将不会处理写入请求，并返回错误。
    2. targetRevisionId 字段设置为要应用写入请求的文档的 revisionId。如果文档在 API 读取请求发出后发生了修改，系统会将写入请求更改应用于协作者更改。写入请求的结果会将写入请求更改和协作者更改合并到文档的新修订版中。Google 文档服务器负责合并内容。

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

考虑标签页

单个文档可以包含多个标签页，这些标签页需要在 API 请求中进行特殊处理。

请注意以下事项：

  1. 在 documents.get 方法中将 includeTabsContent 参数设置为 true，以从文档中的所有标签页检索内容。默认情况下，系统不会返回所有标签页内容。
  2. 指定要在 documents.batchUpdate 方法中应用每个 Request 的标签页 ID。每个 Request 都包含一种用于指定要应用更新的标签页的方法。默认情况下，如果未指定标签页，则在大多数情况下，Request 将应用于文档中的第一个标签页。如需了解详情，请参阅 Request 的文档。