在使用 Google 文档 API 时,您应遵循几项原则。其中包括:
- 反向修改以提高效率
- 制定协作计划
- 使用
WriteControl
确保状态一致性
下文介绍了这些原则。
反向修改以提高效率
在对 BatchUpdate
方法的单次调用中,按索引位置的降序对请求进行排序。这样就无需计算由于插入和删除而导致的索引更改。
制定协作计划
文档状态会发生变化。在方法调用与另一个方法调用之间,其他协作者可能会更新文档,如下图所示:
如果索引错误,这可能会导致错误。由于多个用户使用界面编辑文档,Google 文档会透明地处理此操作,但作为 API 客户端,您的应用必须对此进行管理。即使您不预计会对文档进行协作,也务必采取防御性编程并确保文档状态保持一致。为了确保一致性,请查看下面的 WriteControl
部分。
使用 WriteControl 确保状态一致性
当您阅读并更新文档时,可以使用 BatchUpdate
方法中的 WriteControl
字段来确保文档尚未更新。这样,您就可以在文档版本未更改的情况下修改文档。具体使用方法如下:
- 获取文档并保存其中包含的
revisionId
字符串。 - 编写更新请求。
- 添加一个
WriteControl
对象,并将 requiredRevisionId 设置为您保存的字符串。 - 调用
BatchUpdate
时,如果文档修订版本发生更改,将返回错误且不会执行更新。