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

Дополнительные сведения см. в руководстве по авторизации .

Управление записью

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

Представление 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, изменения, произведенные этим запросом на запись, применяются к изменениям соавтора. Это приводит к новой версии документа, которая включает как изменения соавтора, так и изменения в запросе, при этом сервер Документов разрешает конфликтующие изменения. При использовании идентификатора целевой версии клиент API можно рассматривать как еще одного соавтора документа.

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