Method: documents.batchUpdate

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

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

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

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

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

HTTP-запрос

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

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

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

Параметры
document Id

string

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

Тело запроса

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

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

object ( Request )

Список обновлений, которые можно применить к документу.

write Control

object ( WriteControl )

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

Тело ответа

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

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

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

string

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

replies[]

object ( Response )

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

write Control

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 может быть только одним из следующих:
required Revision Id

string

Необязательный revision ID документа, к которому применяется запрос на запись. Если это не последняя версия документа, запрос не обрабатывается и возвращает ошибку 400 bad request.

Когда в ответе возвращается требуемый идентификатор редакции, он указывает идентификатор редакции документа после применения запроса.

target Revision Id

string

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

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

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