本文說明如何批次處理 API 呼叫,以減少用戶端必須建立的 HTTP 連線數量。
本文件專門說明如何透過傳送 HTTP 要求來提出批次要求。但如果您使用 Google 用戶端程式庫提出批次要求,請參閱用戶端程式庫的說明文件。
總覽
用戶端建立的每個 HTTP 連線都會造成一定程度的負擔。Google Classroom API 支援批次作業,可讓用戶端在單一 HTTP 要求中加入數個 API 呼叫。
以下是您可能想要使用批次作業的狀況範例:
- 為大量課程擷取學生名單。
- 大量建立或更新課程。
- 新增大量課程學生名單。
- 擷取大量使用者的課程清單。
這樣一來,您就能將這些呼叫分組為單一 HTTP 要求,而不必分別傳送每個呼叫。所有內部要求都必須前往同一個 Google API。
單一批次要求最多包含 50 個呼叫。如果您需要超過數量的呼叫,請使用多個批次要求。
注意:Google Classroom API 批次系統使用的語法與 OData 批次處理系統相同,但語意不同。
批次詳細資料
批次要求是由多個 API 呼叫合併成一個 HTTP 要求,可傳送至 API 探索文件中指定的 batchPath
。預設路徑為 /batch/api_name/api_version
。本節詳細說明批次語法,並在後半段提供範例。
注意:一組批次處理的 n 要求會計入 n 要求,而不是一個要求。在處理之前,系統會先將批次要求分成一組要求。
批次要求的格式
批次要求是單一標準 HTTP 要求,內含多個使用 multipart/mixed
內容類型的 Google Classroom API 呼叫。在主要 HTTP 要求中,每個部分都含有一個巢狀的 HTTP 要求。
每個部分都以自己的 Content-Type: application/http
HTTP 標頭開頭。也可以使用選用的 Content-ID
標頭。不過,部分標頭只是用來標示該部分的開頭;這些標頭與巢狀要求各自獨立。伺服器將批次要求解除包裝為不同的要求後,就會忽略部分標頭。
每個分部的主體本身就是一個完整的 HTTP 要求,有自己的動詞、URL、標頭和內文。HTTP 要求只能包含 URL 的路徑部分;批次要求禁止納入完整的 URL。
外部批次要求的 HTTP 標頭 (例如 Content-Type
等 Content-
標頭除外) 會套用至批次中的每個要求。如果您在外部要求和個別呼叫中均指定所提供的 HTTP 標頭,則個別呼叫標頭的值會覆寫外部批次要求標頭的值。個別呼叫的標頭只會套用於該呼叫。
例如,如果您提供 Authorization 標頭用於特定呼叫,則該標頭只會套用於該呼叫。如果您提供 Authorization 標頭用於外部要求,則除非個別呼叫以自己的 Authorization 標頭覆寫所提供的標頭,否則所提供的 Authorization 標頭會套用於所有個別呼叫。
當伺服器收到批次要求時,即會將外部要求的查詢參數和標頭 (在適用情況下) 套用至每一個分部,然後將每個分部視為不同的 HTTP 要求。
回應批次要求
伺服器的回應是包含 multipart/mixed
內容類型的單一標準 HTTP 回應;每個部分都是批次要求中其中一個要求的回應,回應順序與要求順序相同。
就像要求中的分部一樣,每個回應分部都含有完整的 HTTP 回應,包括狀態碼、標頭和內文;如同要求中的部分,每個回應部分前面都會加上 Content-Type
標頭,標示部分開頭。
如果要求的特定部分有 Content-ID
標頭,則回應的對應部分會有相符的 Content-ID
標頭,且原始值前面會加上 response-
字串,如以下範例所示。
注意事項:伺服器得按任意順序執行您的呼叫。不要期望呼叫會按您的指定順序執行。如果您想要確保兩個呼叫依指定順序執行,就不能以單一要求傳送它們,而要先傳送第一個呼叫,然後等到第一個呼叫的回應後才能傳送第二個呼叫。
範例
以下範例顯示如何搭配 Google Classroom API 使用批次作業。
批次要求範例
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--
批次回應範例
這是前一節中範例要求的回應。
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--
使用用戶端程式庫
下列程式碼範例示範如何使用 Google API 用戶端程式庫發出批次要求。如要進一步瞭解如何安裝及設定程式庫,請參閱各自的快速入門指南。
.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)