Richieste batch

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, con insertionIndex di 1, utilizzando il CreateSlideRequest .

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

• 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
   }
}