Solicitações em lote

Este documento mostra como agrupar chamadas de API para reduzir o número de conexões que seu cliente precisa fazer. A execução em lote pode melhorar a eficiência de um aplicativo, diminuindo as viagens de ida e volta de rede e aumentando a capacidade.

Visão geral

Cada conexão feita pelo cliente resulta em certa quantidade de sobrecarga. A API Google Docs oferece suporte a operações em lote para que o cliente coloque vários objetos de solicitação, cada um especificando um único tipo de solicitação a ser realizado, em uma única solicitação em lote. Uma solicitação em lote pode melhorar a performance ao combinar várias subsolicitações em uma única chamada para o servidor, recuperando uma única resposta.

Recomendamos que os usuários sempre agrupem várias solicitações. Confira alguns exemplos de situações em que você pode usar as operações em lote:

  • Você acabou de começar a usar a API e tem muitos dados para fazer upload.
  • Você precisa atualizar metadados ou propriedades, como formatação, em vários objetos.
  • Você precisa excluir muitos objetos.

Limites, autorização e considerações sobre dependência

Confira uma lista de outros itens a serem considerados ao usar a atualização em lote:

  • Cada solicitação em lote, incluindo todas as subsolicitações, é contabilizada como uma solicitação de API para o limite de uso.
  • Uma solicitação em lote é autenticada uma vez. Essa autenticação única é aplicada a todos os objetos de atualização em lote na solicitação.
  • O servidor processa as subsolicitações na mesma ordem em que aparecem na solicitação em lote. As subsolicitações posteriores podem depender de ações realizadas durante subsolicitações anteriores. Por exemplo, na mesma solicitação em lote, os usuários podem inserir texto em um documento e estilizá-lo.

Detalhes do lote

Uma solicitação em lote consiste em uma chamada de método batchUpdate com várias subsolicitações para, por exemplo, adicionar e formatar um documento.

Cada solicitação é validada antes de ser aplicada. Todas as subsolicitações na atualização em lote são aplicadas atomicamente. Ou seja, se uma solicitação não for válida, a atualização inteira vai falhar, e nenhuma das mudanças (potencialmente dependentes) será aplicada.

Algumas solicitações fornecem respostas com informações sobre as solicitações aplicadas. Por exemplo, todas as solicitações de atualização em lote para adicionar objetos retornam respostas para que você possa acessar os metadados do objeto recém-adicionado, como o ID ou título.

Com essa abordagem, é possível criar um documento do Google inteiro usando uma solicitação de atualização em lote da API com várias subsolicitações.

Formato de uma solicitação em lote

Uma solicitação é uma única solicitação JSON que contém várias subsolicitações aninhadas com uma propriedade obrigatória: requests. As solicitações são construídas em uma matriz de solicitações individuais. Cada solicitação usa JSON para representar o objeto de solicitação e conter as propriedades.

Formato de uma resposta em lote

O formato da resposta de uma solicitação em lote é semelhante ao formato da solicitação. A resposta do servidor contém uma resposta completa do único objeto de resposta.

A propriedade do objeto JSON principal é chamada replies. As respostas são retornadas em uma matriz, com cada resposta para uma das solicitações ocupando a mesma ordem de índice da solicitação correspondente. Algumas solicitações não têm respostas, e a resposta nesse índice de matriz está vazia.

Exemplo

O exemplo de código abaixo mostra o uso de lotes com a API Docs.

Solicitação

Este exemplo de solicitação em lote demonstra como:

  • Insira o texto "Hello World" no início de um documento existente, com um índice location de 1, usando o InsertTextRequest.

  • Atualize a palavra "Hello" usando o UpdateTextStyleRequest. startIndex e endIndex definem o range de texto formatado no segmento.

  • Usando textStyle, defina o estilo da fonte como negrito e a cor como azul apenas para a palavra "Hello".

  • Usando o campo WriteControl, é possível controlar como as solicitações de gravação são executadas. Para mais informações, consulte Estabelecer a consistência do estado com WriteControl.

{
   "requests":[
      {
         "insertText":{
            "location":{
               "index":1,
               "tabId":TAB_ID
            },
            "text":"Hello World"
         }
      },
      {
         "updateTextStyle":{
            "range":{
               "startIndex":1,
               "endIndex":6
            },
            "textStyle":{
               "bold":true,
               "foregroundColor":{
                  "color":{
                     "rgbColor":{
                        "blue":1
                     }
                  }
               }
            },
            "fields":"bold,foreground_color"
         }
      }
   ],
   "writeControl": {
      "requiredRevisionId": "REQUIRED_REVISION_ID"
  }
}

Substitua TAB_ID e REQUIRED_REVISION_ID pelo ID da guia e o ID da revisão, respectivamente, do documento em que a solicitação de gravação é aplicada.

Resposta

Este exemplo de resposta em lote mostra informações sobre como cada subsolicitação na solicitação em lote foi aplicada. Nem o InsertTextRequest nem o UpdateTextStyleRequest contêm uma resposta. Portanto, os valores de índice da matriz em [0] e [1] consistem em chaves vazias. A solicitação em lote mostra o objeto WriteControl, que mostra como as solicitações foram executadas.

{
   "replies":[
      {},
      {}
   ],
   "writeControl":{
      "requiredRevisionId":`REQUIRED_REVISION_ID`
   },
   "documentId":`DOCUMENT_ID`
}