Solicitações em lote

Neste documento, mostramos como agrupar chamadas de API em lote para reduzir o número de conexões que seu cliente precisa fazer. O agrupamento em lote pode melhorar a eficiência de um aplicativo ao diminuir os tempos de ida e volta da rede e aumentar a capacidade.

Informações gerais

Cada conexão que seu cliente faz resulta em uma determinada sobrecarga. A API Google Docs é compatível com lotes para permitir que o cliente coloque vários objetos de solicitação, cada um especificando um único tipo de solicitação a ser executada, em uma única solicitação em lote. Uma solicitação em lote pode melhorar o desempenho combinando várias subsolicitações em uma única chamada para o servidor, recuperando uma única resposta de volta.

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

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

Considerações sobre limites, autorização e dependência

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

• Cada solicitação em lote, incluindo todas as subsolicitações, é contabilizada como uma solicitação de API para seu limite de uso.
• Uma solicitação em lote é autenticada uma vez. Essa autenticação única se aplica 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. Subsolicitações posteriores podem depender de ações tomadas durante subsolicitações anteriores. Por exemplo, na mesma solicitação em lote, os usuários podem inserir texto em um documento e depois 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 alguma solicitação não for válida, toda a atualização será malsucedida e nenhuma das alterações (possivelmente 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 o título.

Com essa abordagem, você cria um documento inteiro do Google 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 contendo 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 da solicitação e conter as propriedades dele.

Formato de uma resposta em lote

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

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

Exemplo

O exemplo a seguir 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 InsertTextRequest.
• Atualize a palavra "Hello" usando UpdateTextStyleRequest. O startIndex e o endIndex definem a range do texto formatado no segmento.
• Usando textStyle, defina o estilo da fonte como negrito e a cor como azul.

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

Resposta

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

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