Questo documento mostra come raggruppare le chiamate API per ridurre il numero di connessioni HTTP che il client deve effettuare.
Questo documento riguarda nello specifico l'esecuzione di una richiesta batch tramite l'invio di una richiesta HTTP. Se invece utilizzi una libreria client di Google per effettuare una richiesta batch, consulta la documentazione della libreria client.
Panoramica
Ogni connessione HTTP che il tuo client genera comporta un certo overhead. L'API Google Classroom supporta la creazione di batch, per consentire al client di inserire diverse chiamate API in una singola richiesta HTTP.
Esempi di situazioni in cui potrebbe essere utile utilizzare la creazione in batch:
- Recupero degli elenchi degli studenti per un numero elevato di corsi.
- Creare o aggiornare i corsi in blocco.
- Aggiunta di un numero elevato di elenchi degli studenti del corso.
- Recupero degli elenchi di corsi per un numero elevato di utenti.
In ogni caso, invece di inviare ogni chiamata separatamente, puoi raggrupparle in un'unica richiesta HTTP. Tutte le richieste interne devono essere indirizzate alla stessa API di Google.
Puoi effettuare un massimo di 50 chiamate in una singola richiesta batch. Se devi effettuare più chiamate, utilizza più richieste batch.
Nota: il sistema batch dell'API Google Classroom utilizza la stessa sintassi del sistema di elaborazione batch OData, ma la semantica è diversa.
Dettagli batch
Una richiesta batch è composta da più chiamate API combinate in un'unica richiesta HTTP, che può essere inviata al batchPath
specificato nel documento di rilevamento API. Il percorso predefinito è /batch/api_name/api_version
. In questa sezione viene descritta in dettaglio la sintassi batch; di seguito sarà riportato un esempio.
Nota: un insieme di richieste n raggruppate viene conteggiato ai fini del limite di utilizzo come richieste n, non come una singola richiesta. La richiesta batch viene scomposta in un insieme di richieste prima dell'elaborazione.
Formato di una richiesta in batch
Una richiesta batch è una singola richiesta HTTP standard contenente più chiamate API di Google Classroom, che utilizzano il tipo di contenuti multipart/mixed
. All'interno della richiesta HTTP principale, ciascuna delle parti contiene una richiesta HTTP nidificata.
Ogni parte inizia con la propria intestazione HTTP Content-Type: application/http
. Può anche avere un'intestazione Content-ID
facoltativa. Tuttavia, le intestazioni di parte servono solo a segnare l'inizio della parte e sono separate dalla richiesta nidificata. Dopo che il server ha decriptato la richiesta batch in richieste separate, le intestazioni delle parti vengono ignorate.
Il corpo di ogni parte è stessa una richiesta HTTP completa, con verbo, URL, intestazioni e corpo specifici. La richiesta HTTP deve contenere solo la parte del percorso dell'URL; non sono consentiti URL completi nelle richieste batch.
Le intestazioni HTTP per la richiesta del batch esterno, ad eccezione delle intestazioni Content-
come Content-Type
, si applicano a tutte le richieste del batch. Se specifichi una determinata intestazione HTTP sia nella richiesta esterna che in una singola chiamata, il valore dell'intestazione della singola chiamata sostituisce il valore dell'intestazione della richiesta batch esterna. Le intestazioni di una singola chiamata si applicano solo a quella chiamata.
Ad esempio, se fornisci un'intestazione di autorizzazione per una chiamata specifica, l'intestazione si applica solo a quella chiamata. Se fornisci un'intestazione di autorizzazione per la richiesta esterna, questa si applica a tutte le singole chiamate, a meno che non venga sovrascritta con intestazioni di autorizzazione proprie.
Quando il server riceve la richiesta in batch, applica i parametri di query e le intestazioni della richiesta esterna (a seconda dei casi) a ogni parte, quindi le tratta come se fosse una richiesta HTTP separata.
Risposta a una richiesta batch
La risposta del server è una singola risposta HTTP standard con un tipo di contenuto multipart/mixed
; ogni parte è la risposta a una delle richieste della richiesta in batch, nello stesso ordine delle richieste.
Come le parti della richiesta, ogni parte della risposta contiene una risposta HTTP completa, inclusi un codice di stato, intestazioni e corpo. E come le parti della richiesta, ogni parte della risposta è preceduta da un'intestazione Content-Type
che segna l'inizio della parte.
Se una determinata parte della richiesta aveva un'intestazione Content-ID
, la parte corrispondente della risposta avrà un'intestazione Content-ID
corrispondente, con il valore originale preceduto dalla stringa response-
, come mostrato nell'esempio seguente.
Nota: il server può effettuare le chiamate in qualsiasi ordine. Non fare affidamento sull'esecuzione nell'ordine in cui li hai specificati. Se vuoi assicurarti che vengano effettuate due chiamate in un determinato ordine, non puoi inviarle in una singola richiesta; invia invece la prima da sola e poi attendi la risposta alla prima prima di inviare la seconda.
Esempio
L'esempio seguente mostra l'utilizzo della creazione in batch con l'API Google Classroom.
Esempio di richiesta batch
POST https://classroom.googleapis.com/batch HTTP/1.1 Authorization: Bearer your_auth_token Content-Type: multipart/mixed; boundary=batch_foobarbaz Content-Length: total_content_length --batch_foobarbaz Content-Type: application/http Content-Transfer-Encoding: binary MIME-Version: 1.0 Content-ID: <item1:12930812@classroom.example.com> PATCH /v1/courses/134529639?updateMask=name HTTP/1.1 Content-Type: application/json; charset=UTF-8 Authorization: Bearer your_auth_token { "name": "Course 1" } --batch_foobarbaz Content-Type: application/http Content-Transfer-Encoding: binary MIME-Version: 1.0 Content-ID: <item2:12930812@classroom.example.com> PATCH /v1/courses/134529901?updateMask=section HTTP/1.1 Content-Type: application/json; charset=UTF-8 Authorization: Bearer your_auth_token { "section": "Section 2" } --batch_foobarbaz--
Esempio di risposta batch
Questa è la risposta alla richiesta di esempio nella sezione precedente.
HTTP/1.1 200 Content-Length: response_total_content_length Content-Type: multipart/mixed; boundary=batch_foobarbaz --batch_foobarbaz Content-Type: application/http Content-ID: <response-item1:12930812@classroom.example.com> HTTP/1.1 200 OK Content-Type application/json Content-Length: response_part_1_content_length { "id": "134529639", "name": "Course 1", "section": "Section 1", "ownerId": "116269102540619633451", "creationTime": "2015-06-25T14:23:56.535Z", "updateTime": "2015-06-25T14:33:06.583Z", "enrollmentCode": "6paeflo", "courseState": "PROVISIONED", "alternateLink": "http://classroom.google.com/c/MTM0NTI5NjM5" } --batch_foobarbaz Content-Type: application/http Content-ID: <response-item2:12930812@classroom.example.com> HTTP/1.1 200 OK Content-Type: application/json Content-Length: response_part_2_content_length { "id": "134529901", "name": "Course 1", "section": "Section 2", "ownerId": "116269102540619633451", "creationTime": "2015-06-25T14:23:08.761Z", "updateTime": "2015-06-25T14:33:06.490Z", "enrollmentCode": "so75ha5", "courseState": "PROVISIONED", "alternateLink": "http://classroom.google.com/c/MTM0NTI5OTAx" } --batch_foobarbaz--
Utilizzo delle librerie client
I seguenti esempi di codice mostrano come effettuare richieste in batch utilizzando le librerie client delle API di Google. Consulta le rispettive guide rapide per ulteriori informazioni su come installare e configurare le librerie.
.NET
Java
PHP
Python
course_id = '123456' student_emails = ['alice@example.edu', 'bob@example.edu'] def callback(request_id, response, exception): if exception is not None: print 'Error adding user "{0}" to the course course: {1}'.format( request_id, exception) else: print 'User "{0}" added as a student to the course.'.format( response.get('profile').get('name').get('fullName')) batch = service.new_batch_http_request(callback=callback) for student_email in student_emails: student = { 'userId': student_email } request = service.courses().students().create(courseId=course_id, body=student) batch.add(request, request_id=student_email) batch.execute(http=http)