Method: documents.batchUpdate

对文档应用一个或多个更新。

系统会在应用前验证每个 request。如果任何请求无效，则整个请求将会失败，并且不会应用任何内容。

有些请求会提供 replies，以便为您提供一些有关它们如何应用的信息。其他请求不需要返回信息；每个请求都会返回一个空回复。回复的顺序与请求的顺序一致。

例如，假设您调用批处理更新涉及四个更新，并且只有第三个更新返回信息。回复会依次收到两个空白回复、第三个请求的回复和另一个空白回复。

由于其他用户可能正在编辑文档，所以文档可能无法准确反映您的更改：您的更改可能会因协作者所做的更改而发生变化。如果没有协作者，则该文档应反映您所做的更改。在任何情况下，都可确保请求中的更新以原子方式同时应用。

HTTP 请求

POST https://docs.googleapis.com/v1/documents/{documentId}:batchUpdate

网址采用 gRPC 转码语法。

路径参数

参数
documentId

string

要更新的文档的 ID。

请求正文

请求正文中包含结构如下的数据：

JSON 表示法 
{
  "requests": [
    {
      object (Request)
    }
  ],
  "writeControl": {
    object (WriteControl)
  }
}
字段
requests[]

object (Request)

要应用于文档的更新列表。
writeControl

object (WriteControl)

控制写入请求的执行方式。

响应正文

来自 documents.batchUpdate 请求的响应消息。

如果成功，响应正文将包含结构如下的数据：

JSON 表示法 
{
  "documentId": string,
  "replies": [
    {
      object (Response)
    }
  ],
  "writeControl": {
    object (WriteControl)
  }
}
字段
documentId

string

更新应用到的文档的 ID。
replies[]

object (Response)

最新动态的回复。这会将 1 对 1 与更新一一对应，不过某些请求的回复可能为空。
writeControl

object (WriteControl)

应用请求后更新后的写入控件。

授权范围

需要以下 OAuth 范围之一：

  • https://www.googleapis.com/auth/documents
  • https://www.googleapis.com/auth/drive
  • https://www.googleapis.com/auth/drive.file

如需了解详情，请参阅授权指南。

写入控件

控制写入请求的执行方式。

JSON 表示法 
{

  // Union field control can be only one of the following:
  "requiredRevisionId": string,
  "targetRevisionId": string
  // End of list of possible types for union field control.
}
字段
联合字段 control。确定待写入文档的修订版本，以及如果该修订版本不是文档的当前修订版本时，请求的行为应该如何。如果两个字段均未指定，更新将应用于最新修订版本。control 只能是下列其中一项：
requiredRevisionId

string

应用写入请求的文档的可选 revision ID。如果这不是文档的最新版本，则系统不会处理请求并返回 400 错误请求错误。

当响应中返回所需的修订版本 ID 时，它会指明应用请求后的文档的修订版本 ID。
targetRevisionId

string

应用写入请求的文档的可选目标 revision ID。

如果使用 API 读取文档后协作者发生变化，则此写入请求生成的更改将应用于协作者的更改。这样会导致文档的新修订版本包含协作者所做的更改和请求中的更改，而文档服务器会解决冲突的更改。使用目标修订版本 ID 时，API 客户端可以视为文档的另一个协作者。

目标修订版本 ID 只能用于写入文档的近期版本。如果目标修订版本远远落后于最新版本，系统将不会处理请求并返回 400 错误请求错误。请在检索到最新版本的文档后再次尝试该请求。通常，修订版本 ID 在读取后的几分钟内仍可用作目标修订版本，但对于经常编辑的文档，此窗口可能会更短。