Neste documento, mostramos como agrupar chamadas de API em lotes para reduzir o número de conexões que seu cliente precisa fazer. Os lotes 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 do seu cliente resulta em uma certa quantidade de sobrecarga. A API Google Slides é compatível com lotes para permitir que seu 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.
Incentivamos os usuários a sempre agrupar várias solicitações. Veja alguns exemplos de situações em que é possível usar 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 muitos objetos.
Considerações sobre limites, autorização e dependência
Veja uma lista de outros itens a serem considerados ao implementar a atualização em lote:
- Cada solicitação em lote, incluindo todas as subsolicitações, é contada 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. As subsolicitações mais recentes podem depender das ações realizadas durante as 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 uma apresentação.
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 falhará 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 ID ou título.
Com essa abordagem, você cria um documento do Google inteiro usando uma solicitação de atualização em lote de 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 dele.
Formato de uma resposta em lote
O formato de resposta de uma solicitação em lote é semelhante ao da solicitação. Ela contém uma resposta completa do único objeto de resposta.
A propriedade do objeto JSON principal é 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 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:
Adicione um recurso
presentations.pages
a uma apresentação atual, com uminsertionIndex
de1
, usando o métodoCreateSlideRequest
.Adicione uma
shapeType
do tipoTEXT_BOX
ao novo slide usando o métodoCreateShapeRequest
.Insira o texto "Hello World" no novo campo usando o método
InsertTextRequest
.
{ "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 exibe informações sobre como cada subsolicitação na
solicitação em lote foi aplicada. Observe que o método
InsertTextRequest
não contém uma resposta. Portanto, o valor de índice da matriz em [2]
consiste em chaves vazias. A solicitação em lote exibe a propriedade
WriteControl
, que mostra como as solicitações de gravação foram executadas.
{ "requiredRevisionId": ID "presentationId": "", "replies":[ { "createSlide":{ "objectId":"newSlide" } }, { "createShape":{ "objectId":"newTextBox" } }, { } ], "writeControl":{ "requiredRevisionId": REVISION_ID } }