取得最佳成效的最佳做法

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

  • 反向修改,提高效率
  • 规划协作
  • 使用 WriteControl 字段
  • 将标签页纳入考量

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

反向修改,提高效率

在对 documents.batchUpdate 方法,对请求进行排序, 索引位置的降序。这样就无需计算 索引因插入和删除而发生变化。

规划协作

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

文档在方法调用之间的变化方式。

如果您的索引有误,这可能会导致错误。如果有多位用户修改同一个 文档,Google 文档会透明地处理这个问题。不过, 作为 API 客户端,您的应用必须对其进行管理即使您 进行文档协作时,一定要采取防御性编程方式, 确保文档状态保持一致。为了确保一致性 查看 WriteControl 部分。

使用 WriteControl 建立状态一致性

当您在读取并更新文档时,可以控制 使用 WriteControl documents.batchUpdate 方法中的字段。WriteControl 提供权限 以控制写入请求的执行方式。

以下是使用方式:

  1. 使用 documents.get 方法并保存 revisionId 来自返回的 documents 资源。
  2. 编写您的更新请求。
  3. 添加可选的 WriteControl 对象:
    1. requiredRevisionId 字段设置为 revisionId 应用写入请求的文档。如果文档已被修改 因为 API 读取请求,所以不会处理写入请求, 返回一个错误。
    2. targetRevisionId 字段设置为文档的 revisionId 写入请求。如果文档在 API 读取请求,写入请求的更改将应用于 协作者的更改。写入请求的结果包含 写入请求变更,而协作者则变更为新的 修改文档。Google 文档服务器负责 用于合并内容

如需查看如何使用 WriteControl 构建批量请求的示例,请参阅 这个批量请求示例

将标签页纳入考量

一个文档可以包含多个制表符, 您需要在 API 请求中对请求进行特定处理。

请注意以下几点:

  1. includeTabsContenttrue documents.get 方法 检索文档中所有标签页中的内容。默认情况下,并非所有标签页 内容。
  2. 指定要应用各个 Request 的标签页的 ID 在documents.batchUpdate中将 方法。每个Request 提供一种方式,用于指定要应用更新的标签。默认情况下,如果 未指定标签页时,Request 多数情况下会应用到文档中的第一个标签页。请参阅 Request 秒 文档。