Method: documents.batchUpdate

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

每个 request 都会在应用之前进行验证。如果任何请求无效,则整个请求都会失败,并且不会应用任何更改。

某些请求会带有 replies,以便您了解这些请求的应用方式。其他请求无需返回信息;它们会各自返回一个空回复。回复的顺序与请求的顺序一致。

例如,假设您调用 batchUpdate 并传入四个更新,但只有第三个更新会返回信息。响应中将包含两个空回复、对第三个请求的回复,以及另一个空回复,依此顺序。

由于其他用户可能会修改文档,因此文档可能并不完全反映您的更改:您的更改可能会因协作者的更改而发生变化。如果没有协作者,文档应该会反映您的更改。无论在何种情况下,系统都保证以原子方式同时应用请求中的更新。

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

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

WriteControl

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

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 错误“Bad Request”。

当响应中返回必需的修订 ID 时,该 ID 表示应用请求后的文档修订 ID。

targetRevisionId

string

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

如果在使用 API 读取文档后发生了协作者更改,系统会将此写入请求产生的更改应用于协作者更改。这会生成文档的新修订版本,其中包含协作者所做的更改和请求中的更改,文档服务器会解决冲突的更改。使用目标修订 ID 时,API 客户端可视为文档的另一位协作者。

目标修订 ID 只能用于写入文档的近期版本。如果目标修订版本与最新修订版本相差太远,系统将不处理该请求,并返回 400 错误(请求格式错误)。检索最新版本的文档后,应再次尝试该请求。通常,修订 ID 在被读取后会保留几分钟的有效期,可用作目标修订版本,但对于经常修改的文档,此时间范围可能会更短。