Method: documents.batchUpdate

Применяет одно или несколько обновлений к документу.

Каждый request проверяется перед применением. Если какой-либо запрос недействителен, то весь запрос будет отклонен, и ничего не будет применено.

Некоторые запросы содержат replies , предоставляющие информацию о том, как они применяются. Другие запросы не требуют возврата информации; каждый из них возвращает пустой ответ. Порядок ответов соответствует порядку запросов.

Например, предположим, вы вызываете функцию batchUpdate с четырьмя обновлениями, и только третье возвращает информацию. В ответе будет два пустых сообщения: ответ на третий запрос и еще одно пустое сообщение, именно в таком порядке.

Because other users may be editing the document, the document might not exactly reflect your changes: your changes may be altered with respect to collaborator changes. If there are no collaborators, the document should reflect your changes. In any case, the updates in your request are guaranteed to be applied together atomically.

HTTP-запрос

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

В URL-адресе используется синтаксис транскодирования gRPC .

Параметры пути

Параметры
documentId

string

Идентификатор документа, который необходимо обновить.

Текст запроса

Тело запроса содержит данные следующей структуры:

JSON-представление 
{
  "requests": [
    {
      object (Request)
    }
  ],
  "writeControl": {
    object (WriteControl)
  }
}
Поля
requests[]

object ( Request )

Список изменений, которые необходимо внести в документ.

writeControl

object ( WriteControl )

Обеспечивает контроль над тем, как выполняются запросы на запись.

Ответный текст

Response message from a documents.batchUpdate request.

В случае успеха тело ответа содержит данные следующей структуры:

JSON-представление 
{
  "documentId": string,
  "replies": [
    {
      object (Response)
    }
  ],
  "writeControl": {
    object (WriteControl)
  },
  "suggestionResponses": [
    {
      object (SuggestionResponse)
    }
  ],
  "commentUpdateState": enum (CommentUpdateState)
}
Поля
documentId

string

The ID of the document to which the updates were applied to.

replies[]

object ( Response )

Ответ на обновления. Это соответствует обновлениям в соотношении 1:1, хотя ответы на некоторые запросы могут быть пустыми.

writeControl

object ( WriteControl )

Обновленные параметры управления записью после выполнения запроса.

suggestionResponses[]

object ( SuggestionResponse )

The suggestions which were affected by each update. This maps 1:1 with the updates.

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 )

How the request updates should be applied to the document.

If unspecified, the request updates will be applied as normal edits.

Определяет версию документа, в которую следует записывать данные, и то, как должен вести себя запрос, если эта версия не является текущей. Если ни одно из полей не указано, обновления применяются к последней версии. Ниже приведен список взаимоисключающих полей. В ответе будет установлено не более одного из полей:
requiredRevisionId

string

The optional revision ID of the document the write request is applied to. If this is not the latest revision of the document, the request is not processed and returns a 400 bad request error.

Если в ответе возвращается необходимый идентификатор ревизии, это означает, что идентификатор ревизии документа был изменен после выполнения запроса.

targetRevisionId

string

The optional target revision ID of the document the write request is applied to.

Если после прочтения документа с помощью API произошли изменения, внесенные соавторами, то изменения, созданные этим запросом на запись, применяются к изменениям, внесенным соавторами. В результате создается новая версия документа, которая включает в себя как изменения, внесенные соавторами, так и изменения, указанные в запросе, при этом сервер Docs разрешает конфликтующие изменения. При использовании целевого идентификатора версии клиент API может рассматриваться как еще один соавтор документа.

The target revision ID can only be used to write to recent versions of a document. If the target revision is too far behind the latest revision, the request is not processed and returns a 400 bad request error. The request should be tried again after retrieving the latest version of the document. Usually a revision ID remains valid for use as a target revision for several minutes after it's read, but for frequently edited documents this window might be shorter.

Конец взаимоисключающих областей.

Режим записи

Determines how the request updates should be applied to the document.

Перечисления
WRITE_MODE_UNSPECIFIED The write mode is unspecified. Defaults to EDIT behavior.
EDIT Все обновления применяются как обычно.
SUGGEST Применяйте все обновления в качестве рекомендаций.

ПредложениеОтвет

The suggestions which were affected by a given update.

JSON-представление 
{
  "createdSuggestionIds": [
    string
  ],
  "updatedSummarySuggestionIds": [
    string
  ],
  "deletedSuggestionIds": [
    string
  ],
  "acceptedSuggestionIds": [
    string
  ],
  "rejectedSuggestionIds": [
    string
  ]
}
Поля
createdSuggestionIds[]

string

The IDs of suggestions which were created during the update.

updatedSummarySuggestionIds[]

string

The IDs of suggestions whose summaries were updated during the update.

deletedSuggestionIds[]

string

The IDs of suggestions which were deleted during the update.

acceptedSuggestionIds[]

string

The IDs of suggestions which were accepted during the update.

rejectedSuggestionIds[]

string

The IDs of suggestions which were rejected during the update.

CommentUpdateState

Статус обновления комментариев в пакетном запросе.

Перечисления
COMMENT_UPDATE_STATE_UNSPECIFIED The status of comment updates is unspecified.
NO_UPDATES_REQUESTED В пакетном запросе не запрашивалось никаких обновлений комментариев.
ALL_SAVED Все запрошенные обновления комментариев были внесены в рамках пакетного запроса.
ALL_FAILED_UNKNOWN_REASON Все запрошенные обновления комментариев не удалось.