Z tego dokumentu dowiesz się, jak grupować wywołania interfejsu API, aby zmniejszyć liczbę połączeń HTTP, które musi nawiązać klient.
Ten dokument dotyczy wysyłania żądania zbiorczego przez wysłanie żądania HTTP. Jeśli zamiast tego używasz biblioteki klienta Google do wysyłania operacji grupowych, zapoznaj się z dokumentacją biblioteki klienta.
Omówienie
Każde połączenie HTTP nawiązywane przez klienta powoduje pewien narzut. Interfejs Google Classroom API obsługuje wsadowe wywołania interfejsu API, aby umożliwić klientowi umieszczenie kilku wywołań interfejsu API w jednym żądaniu HTTP.
Przykłady sytuacji, w których warto użyć grupowania:
- Pobieranie list uczestników dla dużej liczby zajęć.
- zbiorcze tworzenie lub aktualizowanie kursów;
- dodawanie dużej liczby list uczestników zajęć;
- Pobieranie list zajęć dla dużej liczby użytkowników.
W obu przypadkach zamiast wysyłać każde wywołanie osobno możesz je pogrupować w pojedyncze żądanie HTTP. Wszystkie żądania wewnętrzne muszą być kierowane do tego samego interfejsu Google API.
W jednym żądaniu zbiorczym możesz utworzyć maksymalnie 50 wywołań. Jeśli musisz wykonać więcej połączeń, użyj wielu zbiorczych próśb.
Uwaga: system przetwarzania zbiorczego interfejsu Google Classroom API używa tej samej składni co system przetwarzania zbiorczego OData, ale ma inną semantykę.
Szczegóły wsadu
Żądanie zbiorcze składa się z kilku wywołań interfejsu API połączonych w jedno żądanie HTTP, które można wysłać do batchPath
określonego w dokumencie z informacjami o interfejsie API. Ścieżka domyślna to /batch/api_name/api_version
. W tej sekcji szczegółowo opisaliśmy składnię poleceń zbiorczych. Poniżej znajdziesz przykład.
Uwaga: zestaw n żądań zebranych w jedną grupę jest liczony jako n żądań, a nie jako jedno żądanie. Przed przetworzeniem żądanie zbiorcze jest dzielone na zestaw żądań.
Format żądania zbiorczego
Żądanie zbiorcze to jedno standardowe żądanie HTTP zawierające wiele wywołań interfejsu Google Classroom API przy użyciu typu treści multipart/mixed
. W ramach tego głównego żądania HTTP każda część zawiera zagnieżdżone żądanie HTTP.
Każda część zaczyna się od własnego nagłówka Content-Type: application/http
HTTP. Może też zawierać opcjonalny nagłówek Content-ID
. Nagłówki części służą jednak tylko do oznaczania początku części i są oddzielone od zagnieżdżonego żądania. Gdy serwer rozpakuje żądanie zbiorcze na osobne żądania, nagłówki części są ignorowane.
Treść każdej części to kompletne żądanie HTTP z własnym czasownikiem, adresem URL, nagłówkami i treścią. Żądanie HTTP musi zawierać tylko ścieżkę adresu URL. W żądaniach zbiorczych nie można używać pełnych adresów URL.
Nagłówki HTTP żądania zbiorczego zewnętrznego, z wyjątkiem nagłówków Content-
, np. Content-Type
, mają zastosowanie do każdego żądania w zbiorczym żądaniu. Jeśli dany nagłówek HTTP jest określony zarówno w żądaniu zewnętrznym, jak i w poszczególnym wywołaniu, wartość nagłówka pojedynczego wywołania zastąpi wartość nagłówka zewnętrznego żądania zbiorczego. Nagłówki pojedynczego połączenia dotyczą tylko tego połączenia.
Jeśli na przykład podasz nagłówek Authorization w przypadku konkretnego wywołania, będzie on dotyczył tylko tego wywołania. Jeśli w żądaniu zewnętrznym podasz nagłówek Authorization, będzie on dotyczył wszystkich poszczególnych wywołań, chyba że zostaną zastąpione przez własne nagłówki Authorization.
Gdy serwer otrzyma żądanie zbiorcze, zastosuje parametry zapytania i nagłówki żądania zewnętrznego (w odpowiednich przypadkach) do każdej części, a potem potraktuje każdą część tak, jakby była osobnym żądaniem HTTP.
Odpowiedź na żądanie zbiorcze
Odpowiedź serwera to pojedyncza standardowa odpowiedź HTTP z typem treści multipart/mixed
. Każda część jest odpowiedzią na jedno z żądań w żądaniu zbiorczym, w tej samej kolejności co żądania.
Podobnie jak części żądania, każda część odpowiedzi zawiera pełną odpowiedź HTTP, w tym kod stanu, nagłówki i treść. Podobnie jak w przypadku części żądania, każdą część odpowiedzi poprzedza nagłówek Content-Type
, który wskazuje początek części.
Jeśli dana część żądania zawierała nagłówek Content-ID
, odpowiadająca jej część odpowiedzi zawiera pasujący nagłówek Content-ID
, a pierwotna wartość jest poprzedzona ciągiem znaków response-
, jak w tym przykładzie.
Uwaga: serwer może wykonywać wywołania w dowolnej kolejności. Nie oczekuj, że będą one wykonywane w kolejności, w jakiej je podano. Jeśli chcesz, aby 2 wywołania były wykonywane w określonej kolejności, nie możesz wysyłać ich w jednym żądaniu. Zamiast tego najpierw wyślij pierwsze wywołanie, a potem poczekaj na odpowiedź na nie, zanim wyślesz drugie.
Przykład
Ten przykład pokazuje użycie grupowania w interfejsie Google Classroom API.
Przykładowe żądanie zbiorcze
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--
Przykład odpowiedzi zbiorczej
Oto odpowiedź na przykładowe żądanie z poprzedniej sekcji.
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--
Korzystanie z bibliotek klientów
Poniższe przykłady kodu pokazują, jak wysyłać żądania zbiorcze za pomocą bibliotek klienta interfejsów API Google. Więcej informacji o instalowaniu i konfigurowaniu bibliotek znajdziesz w odpowiednich krótkich przewodnikach.
.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)