Richieste batch

Questo documento mostra come raggruppare le chiamate API in batch per ridurre il numero di connessioni che il client deve effettuare. Il batching può migliorare l'efficienza di un'applicazione, diminuendo i viaggi di andata e ritorno nella rete e aumentando la velocità effettiva.

Panoramica

Ogni connessione effettuata dal client determina una determinata quantità di overhead. L'API Presentazioni Google supporta la funzionalità batch per consentire al client di inserire più oggetti di richiesta, ognuno dei quali specifica un singolo tipo di richiesta da eseguire, in un'unica richiesta batch. Una richiesta batch può aumentare 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 di situazioni in cui è possibile utilizzare la creazione 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ù oggetti.
• Devi eliminare molti oggetti.

Considerazioni su limiti, autorizzazione e 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 una richiesta API ai fini del limite di utilizzo.
• Una richiesta batch viene autenticata una 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 appaiono nella richiesta batch. Le ultime richieste secondarie 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 applicarne uno stile.

Dettagli batch

Una richiesta batch è composta da una chiamata al metodo batchUpdate con più richieste secondarie per, ad esempio, aggiungere e formattare una presentazione.

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 andrà a buon fine e non verrà applicata nessuna delle modifiche (potenzialmente dipendenti).

Alcune richieste forniscono risposte con informazioni sulle richieste applicate. Ad esempio, tutte le richieste di aggiornamento batch per aggiungere oggetti restituiscono risposte che consentano di accedere ai metadati dell'oggetto appena aggiunto, come l'ID o il titolo.

Con questo approccio puoi creare un intero documento Google utilizzando un'unica richiesta di aggiornamento batch dell'API con più richieste secondarie.

Formato di una richiesta batch

Una richiesta è una singola richiesta JSON contenente più richieste secondarie nidificate con una proprietà obbligatoria: requests. Le richieste sono create in un array di richieste individuali. 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 della richiesta. La risposta del server contiene una risposta completa del singolo oggetto 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 in quell'indice dell'array è vuota.

Esempio

Il seguente esempio di codice mostra l'utilizzo della creazione in batch con l'API Presentazioni.

Richiesta

Questa richiesta batch di esempio dimostra come:

• Aggiungi una risorsa presentations.pages a una presentazione esistente, con insertionIndex di 1, utilizzando il metodo CreateSlideRequest.

• Aggiungi un elemento shapeType di tipo TEXT_BOX alla nuova slide utilizzando il metodo CreateShapeRequest.

• Inserisci il testo "Hello World" nel nuovo campo utilizzando il metodo 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 è stata applicata ogni richiesta secondaria all'interno della richiesta batch. Tieni presente che il metodo InsertTextRequest non contiene una risposta, quindi il valore di indice dell'array in [2] è costituito da parentesi graffe vuote. La richiesta batch non mostra la proprietà 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
   }
}