Method: documents.batchUpdate

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

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

部分请求带有 replies，可为您提供有关其应用方式的一些信息。其他请求不需要返回信息；这些请求各自返回一个空答复。回复的顺序与请求的顺序一致。

例如，假设您使用四个更新调用 batchUpdate，但只有第三个更新返回信息。响应将包含两个空回复、对第三个请求的回复和另一个空回复，按此顺序排列。

由于其他用户可能正在修改文档，因此文档可能无法完全反映您的更改：您的更改可能会因协作者的更改而发生变化。如果没有协作者，文档应会反映您的更改。无论如何，系统保证以原子方式同时应用您请求中的更新。

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)
  },
  "suggestionResponses": [
    {
      object (SuggestionResponse)
    }
  ],
  "commentUpdateState": enum (CommentUpdateState)
}
字段
documentId

string

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

object (Response)

对更新的回复。这与更新一一对应，但对某些请求的回复可能为空。
writeControl

object (WriteControl)

应用请求后的更新写入控制。
suggestionResponses[]

object (SuggestionResponse)

受每次更新影响的建议。此值与更新一一对应。
commentUpdateState

enum (CommentUpdateState)

批量请求中是否应用了评论更新。

授权范围

需要以下 OAuth 范围之一：

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

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

WriteControl

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

JSON 表示法 
{
  "writeMode": enum (WriteMode),

  "requiredRevisionId": string,
  "targetRevisionId": string
}
字段
writeMode

enum (WriteMode)

如何将请求更新应用于文档。

如果未指定，系统将像处理常规修改一样处理更新请求。
联合字段 control。确定要写入的文档的修订版本，以及如果该修订版本不是文档的当前修订版本，请求应如何运行。如果这两个字段均未指定，则更新将应用于最新修订版本。control 只能是下列其中一项：
requiredRevisionId

string

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

如果响应中返回了必需的修订版本 ID，则表示应用请求后文档的修订版本 ID。
targetRevisionId

string

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

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

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

WriteMode

确定应如何将请求更新应用于文档。

枚举
WRITE_MODE_UNSPECIFIED 写入模式未指定。默认采用 EDIT 行为。
EDIT 将所有更新作为正常修改应用。
SUGGEST 以建议的形式应用所有更新。

SuggestionResponse

受指定更新影响的建议。

JSON 表示法 
{
  "createdSuggestionIds": [
    string
  ],
  "updatedSummarySuggestionIds": [
    string
  ],
  "deletedSuggestionIds": [
    string
  ],
  "acceptedSuggestionIds": [
    string
  ],
  "rejectedSuggestionIds": [
    string
  ]
}
字段
createdSuggestionIds[]

string

在更新期间创建的建议的 ID。
updatedSummarySuggestionIds[]

string

在更新期间，摘要已更新的建议的 ID。
deletedSuggestionIds[]

string

更新期间已删除的建议的 ID。
acceptedSuggestionIds[]

string

更新期间接受的建议的 ID。
rejectedSuggestionIds[]

string

在更新期间被拒绝的建议的 ID。

CommentUpdateState

批处理请求中评论更新的状态。

枚举
COMMENT_UPDATE_STATE_UNSPECIFIED 评论更新的状态未指定。
NO_UPDATES_REQUESTED 批量请求中未请求任何评论更新。
ALL_SAVED 批处理请求中请求的所有评论更新均已应用。
ALL_FAILED_UNKNOWN_REASON 所有请求的评论更新均失败。