实现最佳效果的最佳做法

使用 Google Docs API 时，应遵循几项原则。其中包括：

  • 向后修改以提高效率
  • 协作计划
  • 使用 WriteControl 确保状态的一致性

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

向后修改以提高效率

在一次 BatchUpdate 方法调用中，按照索引位置的降序对请求进行排序。这样就无需计算因插入和删除操作而发生的索引更改。

协作计划

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

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

如果索引错误，可能会导致错误。让多位用户使用界面编辑文档时，Google 文档会以透明方式处理文档，但作为 API 客户端，您的应用必须管理此 API。即使您不打算在文档上进行协作，也请务必进行防御性编程，并确保文档状态保持一致。如需了解一种确保一致性的方法，请查看下面的 WriteControl 部分。

使用 WriteControl 确保状态一致性

阅读并更新文档时，您可以使用 BatchUpdate 方法中的 WriteControl 字段确保文档尚未更新。这样，您只会在版本未更改时修改文档。具体使用方法如下：

  1. 获取文档并保存其中包含的 revisionId 字符串。
  2. 编写更新请求。
  3. 添加一个 WriteControl 对象，将 requiredRevisionId 设置为您保存的字符串。
  4. 当您调用 BatchUpdate 时，如果文档修订版本已更改，它会返回错误，并且不会执行更新。