Method: documents.batchUpdate

Aplica uma ou mais atualizações ao documento.

Cada request é validado antes de ser aplicado. Se alguma solicitação não for válida, toda a solicitação vai falhar e nada será aplicado.

Algumas solicitações têm replies para dar informações sobre como elas são aplicadas. Outras solicitações não precisam retornar informações. Cada uma delas retorna uma resposta vazia. A ordem das respostas corresponde à das solicitações.

Por exemplo, suponha que você chame "batchUpdate" com quatro atualizações, e apenas a terceira retorne informações. A resposta teria duas respostas vazias, a resposta à terceira solicitação e outra resposta vazia, nessa ordem.

Como outros usuários podem estar editando o documento, ele pode não refletir exatamente suas mudanças, que podem ser alteradas em relação às mudanças dos colaboradores. Se não houver colaboradores, o documento vai refletir suas mudanças. Em qualquer caso, as atualizações na sua solicitação serão aplicadas juntas de forma atômica.

Solicitação HTTP

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

O URL usa a sintaxe de transcodificação gRPC.

Parâmetros de caminho

Parâmetros
documentId

string

O ID do documento a ser atualizado.

Corpo da solicitação

O corpo da solicitação contém dados com a seguinte estrutura:

Representação JSON 
{
  "requests": [
    {
      object (Request)
    }
  ],
  "writeControl": {
    object (WriteControl)
  }
}
Campos
requests[]

object (Request)

Uma lista de atualizações a serem aplicadas ao documento.
writeControl

object (WriteControl)

Fornece controle sobre como as solicitações de gravação são executadas.

Corpo da resposta

Mensagem de resposta de uma solicitação documents.batchUpdate.

Se bem-sucedido, o corpo da resposta incluirá dados com a estrutura a seguir:

Representação JSON 
{
  "documentId": string,
  "replies": [
    {
      object (Response)
    }
  ],
  "writeControl": {
    object (WriteControl)
  },
  "suggestionResponses": [
    {
      object (SuggestionResponse)
    }
  ],
  "commentUpdateState": enum (CommentUpdateState)
}
Campos
documentId

string

O ID do documento em que as atualizações foram aplicadas.
replies[]

object (Response)

A resposta das atualizações. Isso mapeia 1:1 com as atualizações, embora as respostas a algumas solicitações possam estar vazias.
writeControl

object (WriteControl)

O controle de gravação atualizado após a aplicação da solicitação.
suggestionResponses[]

object (SuggestionResponse)

As sugestões afetadas por cada atualização. Isso é mapeado de forma individual com as atualizações.

commentUpdateState

enum (CommentUpdateState)

Indica se as atualizações de comentários foram aplicadas na solicitação em lote.

Escopos de autorização

Requer um dos seguintes escopos do OAuth:

  • https://www.googleapis.com/auth/documents
  • https://www.googleapis.com/auth/drive
  • https://www.googleapis.com/auth/drive.file

Para mais informações, consulte o guia de autorização.

WriteControl

Fornece controle sobre como as solicitações de gravação são executadas.

Representação JSON 
{
  "writeMode": enum (WriteMode),

  "requiredRevisionId": string,
  "targetRevisionId": string
}
Campos
writeMode

enum (WriteMode)

Como as atualizações de solicitação devem ser aplicadas ao documento.

Se não for especificado, as atualizações de solicitação serão aplicadas como edições normais.

Campo de união control. Determina a revisão do documento em que gravar e como a solicitação deve se comportar se essa revisão não for a atual. Se nenhum dos campos for especificado, as atualizações serão aplicadas à revisão mais recente. control pode ser apenas de um dos tipos a seguir:
requiredRevisionId

string

O revision ID opcional do documento a que a solicitação de gravação é aplicada. Se não for a revisão mais recente do documento, a solicitação não será processada e vai retornar um erro 400 de solicitação inválida.

Quando um ID de revisão obrigatório é retornado em uma resposta, ele indica o ID de revisão do documento após a aplicação da solicitação.
targetRevisionId

string

O revision ID de destino opcional do documento a que a solicitação de gravação é aplicada.

Se houver mudanças feitas por colaboradores depois que o documento foi lido usando a API, as mudanças produzidas por essa solicitação de gravação serão aplicadas às mudanças feitas pelos colaboradores. Isso resulta em uma nova revisão do documento que incorpora as mudanças do colaborador e as mudanças na solicitação, com o servidor dos Documentos resolvendo as mudanças conflitantes. Ao usar o ID da revisão de destino, o cliente da API pode ser considerado outro colaborador do documento.

O ID da revisão de destino só pode ser usado para gravar em versões recentes de um documento. Se a revisão de destino estiver muito desatualizada em relação à mais recente, a solicitação não será processada e vai retornar um erro 400 de solicitação inválida. A solicitação precisa ser tentada novamente depois de recuperar a versão mais recente do documento. Normalmente, um ID de revisão permanece válido para uso como uma revisão de destino por vários minutos após a leitura, mas para documentos editados com frequência, essa janela pode ser menor.

WriteMode

Determina como as atualizações de solicitação devem ser aplicadas ao documento.

Tipos enumerados
WRITE_MODE_UNSPECIFIED O modo de gravação não foi especificado. O padrão é o comportamento EDIT.
EDIT Aplique todas as atualizações como edições normais.
SUGGEST Aplicar todas as atualizações como sugestões.

SuggestionResponse

As sugestões afetadas por uma determinada atualização.

Representação JSON 
{
  "createdSuggestionIds": [
    string
  ],
  "updatedSummarySuggestionIds": [
    string
  ],
  "deletedSuggestionIds": [
    string
  ],
  "acceptedSuggestionIds": [
    string
  ],
  "rejectedSuggestionIds": [
    string
  ]
}
Campos
createdSuggestionIds[]

string

Os IDs das sugestões criadas durante a atualização.
updatedSummarySuggestionIds[]

string

Os IDs das sugestões cujos resumos foram atualizados durante a atualização.
deletedSuggestionIds[]

string

Os IDs das sugestões que foram excluídas durante a atualização.
acceptedSuggestionIds[]

string

Os IDs das sugestões aceitas durante a atualização.
rejectedSuggestionIds[]

string

Os IDs das sugestões que foram rejeitadas durante a atualização.

CommentUpdateState

O status das atualizações de comentários na solicitação em lote.

Tipos enumerados
COMMENT_UPDATE_STATE_UNSPECIFIED O status das atualizações de comentários não foi especificado.
NO_UPDATES_REQUESTED Nenhuma atualização de comentário foi solicitada na solicitação em lote.
ALL_SAVED Todas as atualizações de comentários solicitadas foram aplicadas na solicitação em lote.
ALL_FAILED_UNKNOWN_REASON Falha em todas as atualizações de comentários solicitadas.