Solicitações em lote

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

Visão geral

Cada conexão feita pelo cliente resulta em uma certa quantidade de sobrecarga. A API Google Slides é compatível com o agrupamento em lote para permitir que seu cliente coloque vários objetos de solicitação, cada um especificando um único tipo de solicitação a ser realizada, em uma única solicitação em lote. Uma solicitação em lote pode aumentar o desempenho combinando várias sub-solicitações em uma única chamada ao servidor, recuperando uma única resposta.

Incentivamos os usuários a sempre agrupar várias solicitações em lotes. 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.
  • É necessário atualizar metadados ou propriedades, como formatação, em vários objetos.
  • Você precisa excluir muitos objetos.

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

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

  • Cada solicitação em lote, incluindo todas as sub-solicitações, é contabilizada como uma solicitação de API no 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 sub-solicitações na mesma ordem em que aparecem na solicitação em lote. Os subpedidos posteriores podem depender de ações realizadas durante subpedidos anteriores. Por exemplo, na mesma solicitação em lote, os usuários podem inserir texto em um documento e depois estilizar.

Detalhes do lote

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

Cada solicitação é validada antes de ser aplicada. Todas as subrequisições na atualização em lote são aplicadas atomicamente. Ou seja, se uma solicitação não for válida, toda a atualização 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 ID ou título.

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

Formato de uma solicitação em lote

Uma solicitação é uma única solicitação JSON que contém várias sub-solicitaçõ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 dele.

Formato de uma resposta em lote

O formato da resposta para 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 a 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 a seguir mostra o uso de lotes com a API Slides.

Solicitação

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

{
   "requests":[
      {
         "createSlide":{
            "insertionIndex":1,
            "objectId":"newSlide"
         }
      },
      {
         "createShape":{
            "elementProperties":{
               "pageObjectId":"newSlide",
               "size":{
                  "height":{
                     "magnitude":50,
                     "unit":"PT"
                  },
                  "width":{
                     "magnitude":200,
                     "unit":"PT"
                  }
               }
            },
            "shapeType":"TEXT_BOX",
            "objectId":"newTextBox"
         }
      },
      {
         "insertText":{
            "objectId":"newTextBox",
            "text":"Hello World"
         }
      }
   ]
}

Resposta

Este exemplo de resposta em lote mostra informações sobre como cada subsolicitação dentro da solicitação em lote foi aplicada. O método InsertTextRequest não contém uma resposta. Portanto, o valor do índice da matriz em [2] consiste em chaves vazias. A solicitação em lote mostra a propriedade WriteControl, que indica como as solicitações de gravação foram executadas.

{
   "requiredRevisionId": ID
   "presentationId": "",
   "replies":[
      {
         "createSlide":{
            "objectId":"newSlide"
         }
      },
      {
         "createShape":{
            "objectId":"newTextBox"
         }
      },
      {
         
      }
   ],
   "writeControl":{
      "requiredRevisionId": REVISION_ID
   }
}