取得最佳成效的最佳做法

在使用 Google 文档 API 时,您应遵循几项原则。其中包括:

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

下文介绍了这些原则。

反向修改以提高效率

在对 BatchUpdate 方法的单次调用中,按索引位置的降序对请求进行排序。这样就无需计算由于插入和删除而导致的索引更改。

制定协作计划

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

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

如果索引错误,这可能会导致错误。由于多个用户使用界面编辑文档,Google 文档会透明地处理此操作,但作为 API 客户端,您的应用必须对此进行管理。即使您不预计会对文档进行协作,也务必采取防御性编程并确保文档状态保持一致。为了确保一致性,请查看下面的 WriteControl 部分。

使用 WriteControl 确保状态一致性

当您阅读并更新文档时,可以使用 BatchUpdate 方法中的 WriteControl 字段来确保文档尚未更新。这样,您就可以在文档版本未更改的情况下修改文档。具体使用方法如下:

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