Questo documento mostra come raggruppare le chiamate API per ridurre il numero di connessioni che il client deve effettuare. Il batch può migliorare l'efficienza di un'applicazione riducendo i round trip della rete e aumentando la velocità effettiva.
Panoramica
Ogni connessione stabilita dal client comporta un certo overhead. L'API Documenti Google supporta il raggruppamento per consentire al client di inserire più oggetti di richiesta, ciascuno dei quali specifica un singolo tipo di richiesta da eseguire, in una singola richiesta batch. Una richiesta batch può migliorare le prestazioni combinando più richieste secondarie in un'unica chiamata al server e recuperando una singola risposta.
Invitiamo gli utenti a raggruppare sempre più richieste. Di seguito sono riportati alcuni esempi di situazioni in cui è possibile utilizzare la funzionalità di raggruppamento:
- Hai appena iniziato a utilizzare l'API e hai molti dati da caricare.
- Devi aggiornare i metadati o le proprietà, come la formattazione, su più oggetti.
- Devi eliminare molti oggetti.
Limiti, autorizzazione e considerazioni sulle dipendenze
Di seguito è riportato un elenco di altri elementi da considerare quando si utilizza l'aggiornamento in batch:
- Ogni richiesta batch, incluse tutte le richieste secondarie, viene conteggiata come un'unica richiesta API ai fini del limite di utilizzo.
- Una richiesta batch viene autenticata una sola volta. Questa singola autenticazione si applica a tutti gli oggetti di aggiornamento batch nella richiesta.
- Il server elabora le richieste secondarie nello stesso ordine in cui vengono visualizzate nella richiesta batch. Le richieste secondarie più recenti possono dipendere dalle azioni intraprese durante le richieste secondarie precedenti. Ad esempio, nella stessa richiesta batch, gli utenti possono inserire testo in un documento esistente e assegnare uno stile.
Dettagli batch
Una richiesta batch è costituita da una chiamata al metodo batchUpdate con più richieste secondarie, ad esempio per aggiungere e formattare un documento.
Ogni richiesta viene convalidata prima di essere applicata. Tutte le richieste secondarie nell'aggiornamento batch vengono applicate a livello atomico. Ciò significa che, se una qualsiasi richiesta non è valida, l'intero aggiornamento non va a buon fine e nessuna delle modifiche (potenzialmente dipendenti) viene applicata.
Alcune richieste forniscono risposte con informazioni sulle richieste applicate. Ad esempio, tutte le richieste di aggiornamento batch per aggiungere oggetti restituiscono risposte in modo da poter accedere ai metadati dell'oggetto appena aggiunto, come l'ID o il titolo.
Con questo approccio, puoi creare un intero documento Google utilizzando una singola richiesta di aggiornamento batch API con più richieste secondarie.
Formato di una richiesta in batch
Una richiesta è una singola richiesta JSON contenente più
richieste secondarie nidificate con una proprietà obbligatoria: requests. Le richieste vengono create in un array di singole richieste. Ogni richiesta utilizza
JSON per rappresentare l'oggetto della richiesta e contenere le relative proprietà.
Formato di una risposta in batch
Il formato di risposta per una richiesta in batch è simile al formato della richiesta. La risposta del server contiene una risposta completa del singolo oggetto di risposta.
La proprietà dell'oggetto JSON principale è denominata replies. Le risposte vengono restituite in un array e ogni risposta a una delle richieste occupa lo stesso ordine di indice della richiesta corrispondente. Alcune richieste non hanno risposte e la risposta all'indice dell'array è vuota.
Esempio
L'esempio seguente mostra l'utilizzo della creazione in batch con l'API Documenti.
Richiesta
Questa richiesta batch di esempio mostra come:
- Inserisci il testo "Hello World" all'inizio di un documento esistente, con un indice
Locationpari a 1, utilizzandoInsertTextRequest. - Aggiorna la parola "Hello" utilizzando
UpdateTextStyleRequest.startIndexeendIndexdefiniscono ilrangedel testo formattato all'interno del segmento. - Utilizzando
textStyle, imposta lo stile del carattere su grassetto e il colore su blu.
{
"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"
}
}
]
}
Risposta
Questa risposta batch di esempio mostra informazioni su come è stata applicata ogni richiesta secondaria all'interno della richiesta batch. Tieni presente che sia InsertTextRequest sia UpdateTextStyleRequest non contengono una risposta, quindi i valori di indice dell'array in [0] e [1] sono costituiti da parentesi graffe vuote. La richiesta batch mostra il WriteControl, che mostra come sono state eseguite le richieste di scrittura.
{
"replies":[
{
},
{
}
],
"writeControl":{
"requiredRevisionId":`REVISION_ID`
},
"documentId":`DOCUMENT_ID`
}