Questo documento mostra come raggruppare le chiamate API in batch per ridurre il numero di connessioni che il client deve stabilire. Il batching può migliorare la capacità di efficienza riducendo i viaggi di andata e ritorno di rete e aumentando la velocità effettiva.
Panoramica
Ogni connessione effettuata dal client determina una determinata quantità di overhead. L'API Presentazioni Google supporta la creazione in batch per consentire al cliente di posizionare più oggetti di richiesta, ognuno 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, recuperando una singola risposta.
Invitiamo gli utenti a raggruppare più richieste insieme. Ecco alcuni esempi esempi di situazioni in cui è possibile utilizzare la gestione in batch:
- 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ù di oggetti strutturati.
- Devi eliminare molti oggetti.
Limiti, autorizzazione e considerazioni sulle dipendenze
Di seguito sono riportati un elenco di altri elementi da considerare quando si utilizza l'aggiornamento batch:
- Ogni richiesta batch, incluse tutte le richieste secondarie, viene conteggiata come un'unica API ai fini del limite di utilizzo.
- Una richiesta batch viene autenticata una volta. Questa autenticazione unica si applica a tutti gli oggetti di aggiornamento batch nella richiesta.
- Il server elabora le richieste secondarie nello stesso ordine in cui appaiono nel in una richiesta batch. Le ultime richieste secondarie possono dipendere dalle azioni intraprese durante richieste secondarie precedenti. Ad esempio, nella stessa richiesta batch, gli utenti possono inserire testo in un documento esistente e applicarne uno stile.
Dettagli batch
Una richiesta batch è composta da una chiamata al metodo batchUpdate
con più richieste secondarie, ad esempio per aggiungere e formattare una presentazione.
Ogni richiesta viene convalidata prima di essere applicata. Tutte le richieste secondarie nel batch vengono applicati a livello atomico. Vale a dire che se una qualsiasi richiesta non è valida, l'intero aggiornamento non riesce e nessuno dei problemi (potenzialmente dipendente) vengono applicate le modifiche.
Alcune richieste forniscono risposte con informazioni sulle richieste applicate. Ad esempio, tutte le richieste di aggiornamento in batch per l'aggiunta di oggetti restituiscono risposte in modo che puoi accedere ai metadati dell'oggetto appena aggiunto, come l'ID o titolo.
Con questo approccio, puoi creare un intero documento Google utilizzando un'API di aggiornamento in batch con più richieste secondarie.
Formato di una richiesta batch
Una richiesta è una singola richiesta JSON contenente più file,
richieste secondarie nidificate con una proprietà obbligatoria: requests
. La
vengono create in un array di singole richieste. Ogni richiesta utilizza
JSON per rappresentare l'oggetto della richiesta e contenere le sue proprietà.
Formato di una risposta batch
Il formato della risposta per una richiesta batch è simile al formato di richiesta. La risposta del server contiene una risposta completa del singolo .
La proprietà dell'oggetto JSON principale è denominata replies
. Le risposte
vengono restituiti in un array, con ogni risposta a una delle richieste che
lo stesso ordine di indice della richiesta corrispondente. Alcune richieste non includono
e la risposta all'indice di quell'array è vuota.
Esempio
L'esempio di codice seguente mostra l'utilizzo della modalità batch con API Presentazioni.
Richiesta
Questa richiesta batch di esempio dimostra come:
Aggiungi un
presentations.pages
a una presentazione esistente, coninsertionIndex
di1
, utilizzando ilCreateSlideRequest
.Aggiungi un elemento
shapeType
di tipoTEXT_BOX
alla nuova slide utilizzando ilCreateShapeRequest
: .Inserisci "Hello World" nel nuovo campo utilizzando
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" } } ] }
Risposta
Questa risposta batch di esempio mostra informazioni su come ogni richiesta secondaria all'interno
è stata applicata la richiesta batch. Tieni presente
InsertTextRequest
non contiene una risposta, quindi il valore di indice dell'array in [2]
è costituito da parentesi graffe vuote. La richiesta batch mostra
WriteControl
che mostra come sono state eseguite le richieste di scrittura.
{ "requiredRevisionId": ID "presentationId": "", "replies":[ { "createSlide":{ "objectId":"newSlide" } }, { "createShape":{ "objectId":"newTextBox" } }, { } ], "writeControl":{ "requiredRevisionId": REVISION_ID } }