取得最佳成效的最佳做法

使用 Google Document 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 构建批量请求的示例，请参阅此批量请求示例。