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 (неверный запрос).

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

targetRevisionId

string

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

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

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