เอกสารนี้แสดงวิธีจัดกลุ่มการเรียก API เข้าด้วยกันเพื่อลดจำนวนการเชื่อมต่อ HTTP ที่ไคลเอ็นต์ต้องสร้าง
เอกสารนี้จะกล่าวถึงการส่งคำขอแบบกลุ่มโดยการส่งคำขอ HTTP โดยเฉพาะ หากคุณใช้ไลบรารีของไคลเอ็นต์ Google เพื่อส่งคำขอแบบกลุ่ม โปรดดูเอกสารประกอบของไลบรารีของไคลเอ็นต์
ภาพรวม
การเชื่อมต่อ HTTP แต่ละครั้งที่ไคลเอ็นต์สร้างขึ้นจะทำให้เกิดค่าใช้จ่ายในการประมวลผลจำนวนหนึ่ง Google Classroom API รองรับการจัดกลุ่มเพื่อให้ไคลเอ็นต์ใส่การเรียก API หลายรายการลงในคำขอ HTTP รายการเดียวได้
ตัวอย่างสถานการณ์ที่คุณอาจต้องการใช้การจัดกลุ่ม
- การดึงข้อมูลรายชื่อผู้เรียนสำหรับหลักสูตรจำนวนมาก
- การสร้างหรืออัปเดตหลักสูตรเป็นกลุ่ม
- การเพิ่มรายชื่อผู้เรียนจำนวนมากในหลักสูตร
- การดึงข้อมูลรายการหลักสูตรสำหรับผู้ใช้จำนวนมาก
ในแต่ละกรณี คุณสามารถจัดกลุ่มการเรียกเข้าด้วยกันเป็นคำขอ HTTP รายการเดียวแทนที่จะส่งการเรียกแต่ละรายการแยกกัน คำขอภายในทั้งหมดต้องส่งไปยัง Google API เดียวกัน
คุณส่งการเรียกได้สูงสุด 50 รายการในคำขอแบบกลุ่มรายการเดียว หากต้องส่งการเรียกมากกว่านั้น ให้ใช้คำขอแบบกลุ่มหลายรายการ
หมายเหตุ: ระบบแบบกลุ่มสำหรับ Google Classroom API ใช้ไวยากรณ์เดียวกับระบบการประมวลผลแบบกลุ่มของ OData แต่ความหมายจะแตกต่างกัน
รายละเอียดแบบกลุ่ม
คำขอแบบกลุ่มประกอบด้วยการเรียก API หลายรายการที่รวมกันเป็นคำขอ HTTP รายการเดียว ซึ่งสามารถส่งไปยัง batchPath ที่ระบุไว้ใน เอกสารการค้นพบ API เส้นทางเริ่มต้นคือ /batch/api_name/api_version ส่วนนี้จะอธิบายไวยากรณ์แบบกลุ่มโดยละเอียด และมีตัวอย่างในส่วนถัดไป
หมายเหตุ: ชุดคำขอ n รายการที่จัดกลุ่มเข้าด้วยกันจะนับรวมในขีดจำกัดการใช้งานเป็นคำขอ n รายการ ไม่ใช่คำขอรายการเดียว ระบบจะแยกคำขอแบบกลุ่มออกเป็นชุดคำขอก่อนประมวลผล
รูปแบบของคำขอแบบกลุ่ม
คำขอแบบกลุ่มเป็นคำขอ HTTP มาตรฐานรายการเดียวที่มีการเรียก Google Classroom API หลายรายการ โดยใช้ประเภทเนื้อหา multipart/mixed ภายในคำขอ HTTP หลักนั้น แต่ละส่วนจะมีคำขอ HTTP ที่ซ้อนอยู่
แต่ละส่วนจะเริ่มต้นด้วยส่วนหัว HTTP Content-Type: application/http ของตัวเอง และอาจมีส่วนหัว Content-ID ที่ไม่บังคับด้วย อย่างไรก็ตาม ส่วนหัวของส่วนมีไว้เพื่อทำเครื่องหมายจุดเริ่มต้นของส่วนเท่านั้น โดยจะแยกจากคำขอที่ซ้อนอยู่ หลังจากที่เซิร์ฟเวอร์แยกคำขอแบบกลุ่มออกเป็นคำขอแยกกันแล้ว ระบบจะละเว้นส่วนหัวของส่วน
เนื้อหาของแต่ละส่วนเป็นคำขอ HTTP ที่สมบูรณ์ในตัวเอง โดยมีกริยา, URL, ส่วนหัว และเนื้อหาของตัวเอง คำขอ HTTP ต้องมีเฉพาะส่วนเส้นทางของ URL เท่านั้น ระบบไม่อนุญาตให้ใช้ URL แบบเต็มในคำขอแบบกลุ่ม
ส่วนหัว HTTP สำหรับคำขอแบบกลุ่มภายนอก ยกเว้นส่วนหัว Content- เช่น Content-Type จะมีผลกับทุกคำขอในกลุ่ม หากคุณระบุส่วนหัว HTTP ที่กำหนดไว้ทั้งในคำขอภายนอกและการเรียกแต่ละรายการ ค่าของส่วนหัวของการเรียกแต่ละรายการจะลบล้างค่าของส่วนหัวคำขอแบบกลุ่มภายนอก ส่วนหัวสำหรับการเรียกแต่ละรายการจะมีผลกับการเรียกนั้นๆ เท่านั้น
ตัวอย่างเช่น หากคุณระบุส่วนหัวการให้สิทธิ์สำหรับการเรียกที่เฉพาะเจาะจง ส่วนหัวนั้นจะมีผลกับการเรียกนั้นๆ เท่านั้น หากคุณระบุส่วนหัวการให้สิทธิ์สำหรับคำขอภายนอก ส่วนหัวนั้นจะมีผลกับการเรียกแต่ละรายการทั้งหมด เว้นแต่การเรียกเหล่านั้นจะลบล้างด้วยส่วนหัวการให้สิทธิ์ของตัวเอง
เมื่อเซิร์ฟเวอร์ได้รับคำขอแบบกลุ่ม ระบบจะใช้พารามิเตอร์การค้นหาและส่วนหัวของคำขอภายนอก (ตามความเหมาะสม) กับแต่ละส่วน แล้วถือว่าแต่ละส่วนเป็นคำขอ HTTP แยกกัน
การตอบกลับคำขอแบบกลุ่ม
การตอบกลับของเซิร์ฟเวอร์เป็นการตอบกลับ HTTP มาตรฐานรายการเดียวที่มีประเภทเนื้อหา multipart/mixed โดยแต่ละส่วนเป็นการตอบกลับคำขอรายการใดรายการหนึ่งในคำขอแบบกลุ่มตามลำดับเดียวกับคำขอ
เช่นเดียวกับส่วนต่างๆ ในคำขอ แต่ละส่วนของการตอบกลับจะมี การตอบกลับ HTTP ที่สมบูรณ์ รวมถึง รหัสสถานะ ส่วนหัว และเนื้อหา และเช่นเดียวกับส่วนต่างๆ ในคำขอ แต่ละส่วนของการตอบกลับจะนำหน้าด้วยส่วนหัว Content-Type ที่ทำเครื่องหมายจุดเริ่มต้นของส่วน
หากส่วนใดส่วนหนึ่งของคำขอมีส่วนหัว Content-ID ส่วนที่เกี่ยวข้องของการตอบกลับจะมีส่วนหัว Content-ID ที่ตรงกัน โดยมีค่าเดิมนำหน้าด้วยสตริง response- ดังที่แสดงในตัวอย่างต่อไปนี้
หมายเหตุ: เซิร์ฟเวอร์อาจดำเนินการเรียกของคุณตามลำดับใดก็ได้ อย่าคาดหวังว่าระบบจะดำเนินการตามลำดับที่คุณระบุ หากต้องการให้การเรียก 2 รายการเกิดขึ้นตามลำดับที่กำหนด คุณจะส่งการเรียกเหล่านั้นในคำขอเดียวไม่ได้ แต่ให้ส่งคำขอแรกแยกกัน แล้วรอการตอบกลับคำขอแรกก่อนที่จะส่งคำขอที่ 2
ตัวอย่าง
ตัวอย่างต่อไปนี้แสดงการใช้การจัดกลุ่มกับ 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 APIs ดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีติดตั้งและตั้งค่าไลบรารีได้ในคู่มือเริ่มใช้งานฉบับย่อที่เกี่ยวข้อง
.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)