Method: documents.batchUpdate

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

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

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

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

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

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 )

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

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

Ответное сообщение от запроса documents.batchUpdate .

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

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

string

Идентификатор документа, к которому были применены обновления.

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.

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

targetRevisionId

string

Необязательный revision ID целевого документа, к которому применяется запрос на запись.

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

Идентификатор целевой ревизии можно использовать только для записи в последние версии документа. Если целевая ревизия слишком сильно отстает от последней, запрос не обрабатывается и возвращает ошибку 400 (bad request). Запрос следует повторить после получения последней версии документа. Обычно идентификатор ревизии остается действительным для использования в качестве целевой ревизии в течение нескольких минут после его прочтения, но для часто редактируемых документов этот промежуток может быть короче.