取得最佳成效的最佳做法

使用 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 读取请求之后被修改，则写入请求更改将应用于协作者的更改。写入请求的结果会将写入请求更改和协作者更改合并到文档的新修订版本中。文档服务器负责合并内容。

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