Method: documents.batchUpdate

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

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

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

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

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

HTTP-запрос

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

URL имеет синтаксис gRPC Transcoding.

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

Параметры
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)
  },
  "suggestionResponses": [
    {
      object (SuggestionResponse)
    }
  ],
  "commentUpdateState": enum (CommentUpdateState)
}
Поля
documentId

string

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

object (Response)

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

object (WriteControl)

Обновленный контроль записи после применения запроса.
suggestionResponses[]

object (SuggestionResponse)

Рекомендации, на которые повлияло каждое обновление. Это сопоставляется с обновлениями в соотношении 1:1.
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)

Как применить к документу запрошенные изменения.

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

string

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

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

string

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

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

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

WriteMode

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

Перечисления
WRITE_MODE_UNSPECIFIED Режим записи не указан. По умолчанию используется поведение EDIT.
EDIT Применяйте все обновления как обычные изменения.
SUGGEST Применить все обновления в виде предложений.

SuggestionResponse

Рекомендации, на которые повлияло обновление.

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

string

Идентификаторы подсказок, созданных во время обновления.
updatedSummarySuggestionIds[]

string

Идентификаторы подсказок, чьи краткие описания были обновлены.
deletedSuggestionIds[]

string

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

string

Идентификаторы предложений, принятых во время обновления.
rejectedSuggestionIds[]

string

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

CommentUpdateState

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

Перечисления
COMMENT_UPDATE_STATE_UNSPECIFIED Статус обновления комментариев не указан.
NO_UPDATES_REQUESTED В пакетном запросе не было запросов на обновление комментариев.
ALL_SAVED Все запрошенные изменения комментариев были применены в пакетном запросе.
ALL_FAILED_UNKNOWN_REASON Не удалось обновить все запрошенные комментарии.