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

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

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

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

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

ตัวอย่างเช่น คุณcreate(), patch(), get(), list() และdelete() Classroom Course ได้โดยใช้ API

สร้าง

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

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

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

เมธอด 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 ลักษณะการทํางานของเมธอดเหล่านี้จะแตกต่างกันไป คุณจึงควรอ่านเอกสารประกอบของแต่ละเมธอด