วิธีการทำงานของคำขอ

หน้านี้อธิบายภาพรวมระดับสูงของวิธีการทำงานของคำขอใน Google Classroom API เป้าหมายคือการช่วยเหลือผู้อ่านที่ยังไม่คุ้นเคยกับ การออกแบบที่เน้นทรัพยากรหรือ Google Workspace API

ดูตัวอย่างโค้ดที่เฉพาะเจาะจงได้ในคู่มือ API ที่เกี่ยวข้อง เช่น สร้าง & จัดการหลักสูตรหรือสร้างและจัดการงานในชั้นเรียน

การออกแบบที่เน้นทรัพยากร

ดังที่กล่าวไว้ในแหล่งข้อมูล API, Classroom API ใช้รูปแบบการออกแบบที่มุ่งเน้นทรัพยากร ทรัพยากรส่วนใหญ่มีเมธอดสำหรับการดำเนินการมาตรฐาน เช่น การสร้าง การอ่าน การอัปเดต และการลบอินสแตนซ์ของทรัพยากร

เช่น คุณสามารถ create(), patch(), get(), list() และ delete() Course ของ Classroom โดยใช้ API

สร้าง

หากต้องการสร้างทรัพยากรใหม่ เช่น Course ให้เรียกใช้เมธอด create() สำหรับทรัพยากรที่เกี่ยวข้อง

Create() ต้องระบุรายละเอียดเริ่มต้นที่สำคัญของ ทรัพยากรที่เกี่ยวข้องเป็นอินพุตเสมอ เช่น หากต้องการสร้าง Course ให้เรียกใช้เมธอด create() ในทรัพยากร Course และระบุ name และ description ในคำขอ พร้อมกับข้อมูลที่ไม่บังคับ เช่น room

สำหรับทรัพยากรย่อย (บางครั้งเรียกว่าทรัพยากรลูก) คุณจะต้องระบุตัวระบุสำหรับทรัพยากรหลักด้วย เช่น เมื่อสร้าง CourseWork ภายใน Course คุณต้องใช้ Course id เพื่อระบุว่า CourseWork อยู่ใน Course ใด

Create() จะแสดงผลอินสแตนซ์ของทรัพยากรที่สร้างขึ้นใหม่ในการตอบกลับการเรียก API โดยปกติแล้วทรัพยากรที่ส่งคืนจะมีฟิลด์เพิ่มเติมที่เซิร์ฟเวอร์สร้างขึ้น เช่น id หรือ creationTime

แพตช์

หากต้องการแก้ไขทรัพยากรที่มีอยู่ ให้เรียกใช้เมธอด patch() (ซึ่งบางครั้งเรียกว่า update()) ในทรัพยากรที่เกี่ยวข้อง เมธอด patch() เกือบจะเหมือนกับ create() ทุกประการ แต่มีความแตกต่างที่สำคัญ 2 ประการคือ เมื่อเรียกใช้เมธอด patch() คุณต้องระบุสิ่งต่อไปนี้

1. id ของทรัพยากรที่จะแก้ไข
2. รายการฟิลด์ที่เรียกว่า updateMask เพื่อระบุฟิลด์ใน ทรัพยากรที่จะอัปเดต ซึ่งไม่บังคับในกรณีที่มีชุดฟิลด์เริ่มต้น หรือมีการอนุมานฟิลด์

เคล็ดลับ: คุณอาจเห็นวิธีการ update() ควบคู่ไปกับวิธีการ patch() แม้ว่าทั้ง 2 วิธีจะ แก้ไขทรัพยากร แต่ก็มีลักษณะการทำงานที่แตกต่างกัน Update() จะแทนที่ทรัพยากรด้วยทรัพยากรใหม่ทั้งหมด ในขณะที่ patch() จะอัปเดตเฉพาะฟิลด์ที่เลือก เช่น courses.update() จะแทนที่ Course ที่มีอยู่ทั้งหมด ในขณะที่ courses.patch() จะใช้ fieldMask ที่กล่าวถึงข้างต้นเพื่อแก้ไขเฉพาะฟิลด์ที่เฉพาะเจาะจงใน Course Google Classroom API ใช้ patch() เกือบทั้งหมดเพื่อให้ใช้งานได้ง่าย และเราขอแนะนำให้คุณใช้วิธีนี้โดยทั่วไป

เมธอด Patch() จะแสดงอินสแตนซ์แบบเต็มของทรัพยากรที่อัปเดตในการตอบกลับการเรียก API โดยมีการเปลี่ยนแปลงทั้งหมดเสร็จสมบูรณ์

รับและแสดงรายการ

การดึงข้อมูลทรัพยากรทำได้ 2 วิธี ได้แก่ get() และ list()

เมธอด get() จะดึงข้อมูลทรัพยากรที่เฉพาะเจาะจงตามตัวระบุ เช่น การดึงข้อมูล Course ตาม id หรือ alias การเรียก get() จะแสดงทรัพยากรทั้งหมดโดยตรง

เมธอด list() จะดึงข้อมูลทรัพยากรหลายรายการที่มีประเภทเดียวกันในคำขอเดียวโดยไม่ต้องใช้ตัวระบุทรัพยากรแต่ละรายการ โดยปกติแล้ว list() จะดึงข้อมูลทรัพยากรย่อยทั้งหมดของทรัพยากรหลักบางรายการ เช่น การดึงข้อมูล CourseWork ทั้งหมดภายใน Course ซึ่งจะเป็นประโยชน์ในการ ลดจำนวนคำขอ เมื่อเทียบกับการเรียกใช้ get() หลายครั้ง และมี ประโยชน์อย่างยิ่งเมื่อคุณไม่ทราบ id ของทรัพยากรที่ต้องการ

โดยทั่วไปแล้ว เมธอด list() จะมีจำนวนทรัพยากรสูงสุดที่สามารถ ส่งคืนในการเรียกครั้งเดียว และสามารถกำหนดขีดจำกัดที่ต่ำกว่าได้โดยการรวมค่า pageSize ไว้กับการเรียก ในกรณีที่มีทรัพยากรมากกว่า ขีดจำกัด เมธอด list() จะรองรับการแบ่งหน้า โดยผลลัพธ์แต่ละ "หน้า" ที่ส่งคืนจะมี pageToken ซึ่งสามารถรวมไว้ในการเรียก list() ครั้งถัดไปเพื่อดึงข้อมูลทรัพยากรชุดถัดไป

ลบ

เมธอด delete() จะยอมรับตัวระบุทรัพยากร เช่น id และลบทรัพยากรที่เกี่ยวข้อง หาก delete() สำเร็จ ระบบจะแสดงการตอบกลับที่ว่างเปล่า

การดำเนินการอื่นๆ

การดำเนินการบางอย่างที่ทำได้ด้วย Classroom API อาจทำไม่ได้ ด้วยการดำเนินการมาตรฐานที่กล่าวถึงข้างต้น เช่น การแก้ไข ผู้รับมอบหมายของทรัพยากร CourseWork ในกรณีเหล่านี้ คุณจะใช้เมธอดที่กำหนดเองได้ เช่น เมธอด modifyAssignees ลักษณะการทำงานของเมธอดเหล่านี้ ได้รับการปรับแต่งมาโดยเฉพาะ และคุณควรดูเอกสารประกอบของเมธอดแต่ละรายการ