取得最佳成效的最佳做法

使用 Google Docs 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 读取请求以来已发生修改，则写入请求更改会根据协作者更改进行应用。写入请求的结果会将写入请求更改和协作者更改都纳入文档的新修订版本中。文档服务器负责合并内容。

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

考虑标签页

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

请注意以下几点：

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