Este documento mostra como agrupar chamadas de API em lote para reduzir o número de conexões que seu cliente precisa fazer. Os lotes podem melhorar a eficiência, diminuindo as idas e voltas da rede e aumentando a capacidade.
Visão geral
Cada conexão que seu cliente faz resulta em uma determinada quantidade de sobrecarga. A API Google Docs oferece suporte a 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 combinar 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 em lote. Confira 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 carregar.
- Você precisa atualizar os metadados ou as propriedades, como a formatação, em vários objetos.
- É preciso excluir muitos objetos.
Limites, autorização e considerações sobre a dependência
Veja uma lista de outros itens a serem considerados ao empregar a atualização em lote:
- Cada solicitação em lote, incluindo todas as subsolicitações, é contada como uma API. solicitação em relação ao seu 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 no uma solicitação em lote. As últimas subsolicitações 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 existente 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 no lote atualização são aplicados atomicamente. Ou seja, se alguma solicitação não for válida, o a atualização inteira falha e nenhum dos (potencialmente dependente) alterações sejam aplicadas.
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, você poderá acessar os metadados do objeto recém-adicionado, como o ID ou título.
Com essa abordagem, você pode criar um documento Google inteiro usando uma API de atualização em lote 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
. O
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 suas propriedades.
Formato de uma resposta em lote
O formato de resposta de uma solicitação em lote é semelhante à o formato da solicitação. A resposta do servidor contém uma resposta completa do único objeto de resposta.
A propriedade do objeto JSON principal é denominada replies
. As respostas
em uma matriz, com cada resposta a uma das solicitações ocupando
mesma ordem de índice que a solicitação correspondente. Algumas solicitações não têm
respostas e a resposta no índice da matriz estiver vazia.
Exemplo
O exemplo de código a seguir mostra o uso de lotes com a API Docs.
Solicitação
Este exemplo de solicitação em lote demonstra como:
Insira "Hello World" no início de um documento existente, com uma índice
location
de1
, usando oInsertTextRequest
.Atualize a palavra "Hello" usando o método
UpdateTextStyleRequest
startIndex
eendIndex
definem arange
do texto formatado na o segmento.Usando
textStyle
, defina o estilo da fonte como negrito e a cor como azul para apenas a palavra "Hello".Como usar o
WriteControl
é possível controlar como as solicitações de gravação são executadas. Para mais da rede, consulte Estabelecer consistência de 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 por o ID da guia e o ID da revisão, respectivamente, do documento da solicitação de gravação é aplicada.
Resposta
Esta resposta em lote de exemplo exibe informações sobre como cada subsolicitação em
a solicitação em lote foi aplicada. Nem o
InsertTextRequest
ou o
UpdateTextStyleRequest
contêm uma resposta, então os valores de índice da matriz em [0] e [1] consistem em
de chaves vazias. A solicitação em lote exibe o objeto WriteControl
,
que mostra como as solicitações foram executadas.
{ "replies":[ {}, {} ], "writeControl":{ "requiredRevisionId":`REQUIRED_REVISION_ID` }, "documentId":`DOCUMENT_ID` }