เอกสารนี้แสดงวิธีเรียก 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 รายการ ไม่ใช่ 1 รายการตามขีดจํากัดการใช้งาน ระบบจะแยกคำขอเป็นชุดคำขอก่อนดำเนินการ
รูปแบบคำขอแบบเป็นกลุ่ม
คำขอกลุ่มคือคำขอ HTTP มาตรฐานรายการเดียวที่มีการเรียกใช้ Google Classroom API หลายรายการ โดยใช้ประเภทเนื้อหา multipart/mixed
ภายในคําขอ HTTP หลักนั้น แต่ละส่วนจะมีคําขอ HTTP ที่ฝังอยู่
แต่ละส่วนจะเริ่มต้นด้วยส่วนหัว Content-Type: application/http
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 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)