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

หน้านี้อธิบายภาพรวมระดับสูงเกี่ยวกับวิธีการทำงานของคำขอใน 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 เพื่อระบุช่องในแหล่งข้อมูลที่จะอัปเดต ฟิลด์นี้ไม่บังคับในกรณีที่มีชุดฟิลด์เริ่มต้นหรือระบบอนุมานฟิลด์

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