W tym dokumencie pokazujemy, jak łączyć wywołania interfejsu API w żądania wsadowe, aby zmniejszyć liczbę połączeń HTTP, które musi nawiązać klient.
Ten dokument dotyczy konkretnie wysyłania żądania zbiorczego za pomocą żądania HTTP. Jeśli do wysyłania żądań zbiorczych używasz biblioteki klienta Google, zapoznaj się z dokumentacją biblioteki klienta.
Przegląd
Każde połączenie HTTP nawiązywane przez klienta wiąże się z określonym narzutem. Interfejs Google Classroom API obsługuje grupowanie, dzięki czemu klient może umieścić kilka wywołań interfejsu API w jednym żądaniu HTTP.
Przykłady sytuacji, w których warto używać przetwarzania wsadowego:
- pobieranie list uczniów z dużej liczby kursów.
- Zbiorcze tworzenie lub aktualizowanie kursów.
- dodawanie dużej liczby list uczestników zajęć;
- Pobieranie list kursów dla dużej liczby użytkowników.
W każdym z tych przypadków zamiast wysyłać każde wywołanie osobno możesz zgrupować je w jednym żądaniu HTTP. Wszystkie żądania wewnętrzne muszą być kierowane do tego samego interfejsu API Google.
W jednym żądaniu zbiorczym możesz wykonać maksymalnie 50 wywołań. Jeśli musisz wykonać więcej wywołań, użyj kilku żądań zbiorczych.
Uwaga: system przetwarzania zbiorczego interfejsu Google Classroom API używa tej samej składni co system przetwarzania zbiorczego OData, ale różni się od niego 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 wykrywania interfejsu API. Ścieżka domyślna to /batch/api_name/api_version
. W tej sekcji szczegółowo opisujemy składnię plików wsadowych. Przykład znajdziesz w dalszej części artykułu.
Uwaga: zestaw n żądań połączonych w pakiet jest liczony do limitu wykorzystania jako n żądania, a nie jako 1 żądanie. Przed przetworzeniem żądanie zbiorcze jest dzielone na zestaw żądań.
Format żądania zbiorczego
Żądanie zbiorcze to pojedyncze standardowe żądanie HTTP zawierające wiele wywołań interfejsu Google Classroom API, które korzysta z typu treści multipart/mixed
. W tym głównym żądaniu HTTP każda z części zawiera zagnieżdżone żądanie HTTP.
Każda część zaczyna się od własnego Content-Type: application/http
nagłówka HTTP. Może też zawierać opcjonalny Content-ID
nagłówek. 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 są dozwolone pełne adresy URL.
Nagłówki HTTP zewnętrznego żądania zbiorczego, z wyjątkiem nagłówków Content-
, takich jak Content-Type
, mają zastosowanie do każdego żądania w partii. Jeśli podasz dany nagłówek HTTP zarówno w żądaniu zewnętrznym, jak i w pojedynczym 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 dla konkretnego wywołania, będzie on dotyczył tylko tego wywołania. Jeśli podasz nagłówek autoryzacji dla żądania zewnętrznego, będzie on obowiązywać we wszystkich poszczególnych wywołaniach, chyba że zastąpią go własne nagłówki autoryzacji.
Gdy serwer otrzyma żądanie zbiorcze, zastosuje do każdej jego części parametry zapytania i nagłówki żądania zewnętrznego (w odpowiedni sposób), a następnie potraktuje każdą część tak, jakby była osobnym żądaniem HTTP.
Odpowiedź na żądanie zbiorcze
Odpowiedź serwera to pojedyncza standardowa odpowiedź HTTP o multipart/mixed
typie treści. Każda jej 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 kompletną odpowiedź HTTP, w tym kod stanu, nagłówki i treść. Podobnie jak w przypadku części żądania, każda część odpowiedzi jest poprzedzona nagłówkiem Content-Type
, który oznacza początek tej części.
Jeśli dana część żądania zawierała nagłówek Content-ID
, odpowiednia część odpowiedzi zawiera pasujący nagłówek Content-ID
, w którym przed pierwotną wartością znajduje się ciąg znaków response-
, jak pokazano w przykładzie poniżej.
Uwaga: serwer może wykonywać wywołania w dowolnej kolejności. Nie zakładaj, że zostaną one wykonane w kolejności, w jakiej zostały określone. Jeśli chcesz mieć pewność, że 2 wywołania nastąpią w określonej kolejności, nie możesz wysłać ich w jednym żądaniu. Zamiast tego wyślij najpierw pierwsze wywołanie, a potem poczekaj na odpowiedź, zanim wyślesz drugie.
Przykład
Ten przykład pokazuje użycie przetwarzania wsadowego 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ładowa odpowiedź zbiorcza
To jest 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 klienta
Poniższe przykłady kodu pokazują, jak wysyłać żądania wsadowe przy użyciu bibliotek klienta interfejsów API Google. Więcej informacji o instalowaniu i konfigurowaniu bibliotek znajdziesz w odpowiednich przewodnikach dla początkujących.
.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)