โครงสร้าง API

คู่มือนี้จะแสดงภาพรวมของคอมโพเนนต์หลักที่ประกอบกันเป็น Google Classroom API Google Classroom API ประกอบด้วยทรัพยากรและบริการ ทรัพยากรแสดงถึงเอนทิตีใน Google Classroom เช่น หลักสูตรหรืองาน และบริการจะดึงข้อมูลและจัดการทรัพยากรเหล่านี้ เอนทิตีบางรายการมีพร็อพเพอร์ตี้เพิ่มเติมสำหรับ API โดยเฉพาะนอกเหนือจากที่มีอยู่ใน Classroom ประเภทเอนทิตีหลักมีดังนี้

เอนทิตี	การแทนใน Classroom
หลักสูตร	ชั้นเรียน เช่น "M. คณิตศาสตร์คาบ 4 ของ Smith"
ชื่อแทน	รหัสอื่นสำหรับหลักสูตร
คำเชิญ	วิธีเพิ่มผู้ใช้ในชั้นเรียน
นักเรียน	นักเรียนในชั้นเรียน
ครู	ครูในชั้นเรียน
โปรไฟล์ผู้ใช้	โดยทั่วไปแล้วคือผู้ใช้ ซึ่งอยู่นอกเหนือบริบทของนักเรียนหรือครู
CourseWork	งานในชั้นเรียน
StudentSubmissions	งานของนักเรียนสำหรับงานที่กำหนด เช่น คำตอบหรือเวิร์กชีต
CourseWorkMaterials	สื่อสำหรับนักเรียนในชั้นเรียน
ประกาศ	ประกาศถึงนักเรียนในชั้นเรียน
AddOnAttachment	เนื้อหาหรือกิจกรรมในงานหรือสื่อที่มักจะแสดงเป็น iframe ที่ฝัง
หัวข้อ	การจัดกลุ่มงานและเนื้อหาในชั้นเรียนแบบภาพ
การลงทะเบียน	วิธีการส่งการแจ้งเตือนไปยังแอปสำหรับการเปลี่ยนแปลงของข้อมูล เช่น บัญชีรายชื่อชั้นเรียน

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

ดูข้อมูลโดยละเอียดเกี่ยวกับแหล่งข้อมูลและเมธอดของ API ได้ที่ เอกสารอ้างอิง Classroom API

ภาพรวมความสัมพันธ์ของทรัพยากร

• หลักสูตรคือออบเจ็กต์ข้อมูลพื้นฐานใน Google Classroom
• ระบบจะใช้อีเมลแทนเป็นตัวระบุทางเลือกสําหรับ Courses
• คำเชิญใช้เพื่อเชิญโปรไฟล์ผู้ใช้ให้กลายเป็นครูหรือนักเรียนใน Course แต่ผู้ดูแลระบบโดเมน Google Workspace for Education ก็สามารถเพิ่มผู้ใช้ได้โดยตรงเช่นกัน
• ครูสร้างรายการสตรีมและแชร์กับนักเรียนในหลักสูตร ประเภทรายการสตรีมที่เป็นไปได้ ได้แก่ งาน, สื่อสำหรับงาน และ ประกาศ CourseWork และ CourseWorkMaterials สามารถจัดระเบียบเป็นหัวข้อได้ และมีไฟล์แนบของส่วนเสริม นักเรียนส่ง StudentSubmissions สำหรับ CourseWork
• นักพัฒนาแอปสามารถสร้างการลงทะเบียนเพื่อรับการแจ้งเตือนเมื่อมีการเปลี่ยนแปลงข้อมูลบางอย่าง

Google Classroom มีให้บริการในโดเมนที่สมัครใช้บริการ Google Workspace for Education โดเมนในบริบทของ Classroom มักจะแสดงถึงเขตการศึกษา คุณสามารถสร้างโดเมนทดสอบ Google Workspace for Education เพื่อวัตถุประสงค์ในการพัฒนา ซึ่งจะช่วยให้คุณควบคุมอินสแตนซ์เวอร์ชันที่ใช้งานจริงของ Classroom ได้โดยไม่ส่งผลกระทบต่อผู้ใช้จริง

หลักสูตรและชื่อแทน

Courses แสดงคลาส เช่น "M. คณิตศาสตร์คาบเรียนที่ 4 ของ Smith" รวมถึงครูที่มอบหมาย บัญชีรายชื่อนักเรียน และข้อมูลเมตา แต่ละหลักสูตรจะระบุด้วยรหัสที่ไม่ซ้ำกันซึ่งเซิร์ฟเวอร์กำหนด แหล่งข้อมูล Course จะสรุปข้อมูลเมตาทั้งหมดเกี่ยวกับหลักสูตรโดยเฉพาะ เช่น ชื่อ คำอธิบาย สถานที่ตั้ง และเวลา บัญชีรายชื่อหลักสูตรจะมีการจัดการผ่านแหล่งข้อมูลนักเรียน ครู และคำเชิญรวมถึงวิธีการของหลักสูตร

Aliases คือตัวระบุอื่นสำหรับชั้นเรียนที่อาจเชื่อมโยงกับหลักสูตรและใช้แทนรหัสที่ไม่ซ้ำ โดยแต่ละอีเมลแทนที่จะมีอยู่ในเนมสเปซที่จำกัดผู้ที่สามารถสร้างและดูอีเมลแทนนั้นได้ ระบบรองรับเนมสเปซ 2 รายการดังนี้

• โดเมน: เนมสเปซโดเมนมีประโยชน์ในการสร้างอีเมลแทนที่ผู้ใช้ทุกคนจำเป็นต้องเข้าถึง แต่ไม่ได้เจาะจงสำหรับโปรแกรมใดโปรแกรมหนึ่ง เช่น ควรสร้างข้อมูลทางเลือกสำหรับหลักสูตร เช่น MATH 127 และ COMSCI 127 ในเนมสเปซของโดเมน มีเพียงผู้ดูแลระบบโดเมนเท่านั้นที่สร้างอีเมลแทนในเนมสเปซของโดเมนได้ แต่ผู้ใช้ทุกคนในโดเมนจะเห็นอีเมลแทนดังกล่าว
• โปรเจ็กต์ของนักพัฒนาแอป: เนมสเปซของโปรเจ็กต์ของนักพัฒนาแอปมีประโยชน์ในการจัดการอีเมลแทนที่เฉพาะเจาะจงสำหรับแอปพลิเคชัน ตัวอย่างเช่น แอปพลิเคชันที่ใช้ตัวระบุอื่นสำหรับหลักสูตรสามารถสร้างชื่อแทนเพื่อแมปตัวระบุกับหลักสูตรใน Classroom ได้ ชื่อแทนที่สร้างในเนมสเปซนี้จะเชื่อมโยงกับคอนโซล Google API ที่เฉพาะเจาะจง ผู้ใช้แอปพลิเคชันทุกคนสามารถสร้างและดูอีเมลแทนได้ในเนมสเปซสําหรับโปรเจ็กต์นักพัฒนาแอปพลิเคชันนั้น

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

บัญชีรายชื่อและผู้ใช้ในหลักสูตร

Students และ Teachers เป็นการแมปที่เฉพาะเจาะจงระหว่างโปรไฟล์ผู้ใช้กับหลักสูตร ซึ่งแสดงถึงบทบาทของผู้ใช้รายนั้นในหลักสูตร การกำหนดสถานะนักเรียนและครูไม่ใช่การกำหนดแบบรวม: ผู้ใช้อาจได้รับมอบหมายให้เป็นครูในหลักสูตรหนึ่งและนักเรียนในอีกหลักสูตรหนึ่ง การแต่งตั้ง "นักเรียน" หรือ "ครู" หมายถึงชุดสิทธิ์ สำหรับผู้ใช้รายหนึ่งๆ ในหลักสูตรหนึ่งๆ

นักเรียน/นักศึกษา

ทรัพยากร Student แสดงถึงผู้ใช้ที่ลงทะเบียนเป็นนักเรียนในหลักสูตรที่เฉพาะเจาะจง

นักเรียนจะดูรายละเอียดหลักสูตรและครูของหลักสูตรนั้นได้

ครู

แหล่งข้อมูล Teacher แสดงถึงผู้ใช้ที่สอนหลักสูตรที่เฉพาะเจาะจง

ครูมีสิทธิ์ดูและเปลี่ยนแปลงรายละเอียดหลักสูตร ดูครูและนักเรียน รวมถึงจัดการครูและนักเรียนคนอื่นๆ

Invitations และเมธอดที่เกี่ยวข้องเป็นวิธีที่สะดวกในการเพิ่มนักเรียนและครูลงในหลักสูตร การสร้างคำเชิญช่วยให้ผู้ใช้เลือกได้ว่าจะเข้าร่วมหลักสูตรหรือไม่ แทนที่คุณจะต้องเพิ่มผู้ใช้โดยตรงผ่านแหล่งข้อมูลของครูและนักเรียน

UserProfiles แสดงการแมปกับโปรไฟล์โดเมนของผู้ใช้ตามที่ระบุโดยรหัสที่ไม่ซ้ำหรืออีเมลของผู้ใช้ที่ Directory API แสดง ผู้ใช้ปัจจุบันอาจอ้างอิงรหัสของตนเองโดยใช้ชวเลข "me" ก็ได้

นอกจากนี้ คุณยังใช้บริการ UserProfiles เพื่อจัดการและเชิญ Guardians ซึ่งเป็นการแมประหว่างนักเรียนกับผู้ปกครองได้ด้วย ผู้ปกครองใน Classroom มีสิทธิ์เข้าถึงข้อมูลบางอย่างของนักเรียน เช่น งาน

โปรดดูข้อมูลเพิ่มเติมเกี่ยวกับการจัดการบัญชีรายชื่อที่หัวข้อจัดการครูและนักเรียน

งานในหลักสูตรและงานที่นักเรียนส่ง

รายการ CourseWork แสดงงาน 1 รายการที่มอบหมายให้กับกลุ่มนักเรียนในหลักสูตร โดยจะมีรายละเอียดต่างๆ เช่น คำอธิบาย วันครบกำหนด และเนื้อหา รวมถึงข้อมูลเมตา เช่น เวลาที่สร้าง เนื้อหาประกอบด้วยชื่อ ภาพปก และ URL รวมถึงตัวระบุที่สามารถใช้กับ API ที่เหมาะสม (เช่น ไดรฟ์, YouTube)

รายการ CourseWork อธิบายงานประเภทใดประเภทหนึ่งต่อไปนี้

• งานซึ่งนักเรียนทำเสร็จแล้วโดยส่งเวิร์กชีตหรือไฟล์แนบอื่นๆ
• คำถามที่ต้องการคำตอบสั้นๆ หรือคำถามแบบหลายตัวเลือก

งานของนักเรียนสำหรับรายการ CourseWork จะแสดงด้วย StudentSubmission ซึ่งประกอบด้วยคำตอบและข้อมูลเมตาเพิ่มเติม เช่น สถานะและคะแนนที่ได้รับ

เนื้อหาของ StudentSubmission จะขึ้นอยู่กับประเภทของรายการ CourseWork ที่เกี่ยวข้อง ดังนี้

• เวิร์กชีตและไฟล์แนบที่ส่งสำหรับงาน ซึ่งรวมถึงชื่อ ภาพขนาดย่อ และ URL ตลอดจนตัวระบุที่ใช้ร่วมกับ API ที่เหมาะสมได้ เช่น ไดรฟ์หรือ YouTube
• การตอบกลับคำถามที่ต้องการคำตอบสั้นๆ หรือคำถามแบบหลายตัวเลือก

ดูข้อมูลเพิ่มเติมเกี่ยวกับการจัดการงานและงานที่ส่งของนักเรียนได้ที่หัวข้อจัดการงานของชั้นเรียน

เนื้อหาและประกาศเกี่ยวกับหลักสูตร

CourseWorkMaterials แสดงเนื้อหาที่กำหนดให้กับกลุ่มนักเรียนในหลักสูตร โดยมีรายละเอียด เช่น ชื่อและคําอธิบาย รวมถึงสื่อCourseWork แต่ CourseWorkMaterials ต่างจาก CourseWork ตรงที่ไม่ได้กำหนดให้นักเรียนต้องส่งอาร์ติแฟกต์ ดังนั้นจึงไม่มีวันที่ครบกำหนด และStudentSubmissionsไม่มีอยู่สำหรับ CourseWorkMaterials ครูอาจใช้ CourseWorkMaterials เพื่อโพสต์คำแนะนำให้อ่าน ประมวลรายวิชา หรือกฎของชั้นเรียน เป็นต้น

Announcements ยังแสดงเนื้อหาที่แชร์กับกลุ่มนักเรียนด้วย แต่ไม่มีรายละเอียด เช่น ชื่อ และจัดระเบียบตาม Topics ไม่ได้ เช่น CourseWork หรือ CourseWorkMaterials ครูอาจใช้ฟีเจอร์นี้เพื่อประกาศช่วยเตือนหรือการแจ้งเตือนให้ชั้นเรียนทราบ

หัวข้อ

Topics ใช้เพื่อจัดระเบียบ CourseWork และ CourseWorkMaterials ให้เห็นภาพภายในชั้นเรียน ซึ่งอาจนำไปใช้จัดกลุ่มงานออกเป็น "ไม่บังคับ" และ "จำเป็น" หรือ "หน่วย 1" และ "หน่วย 2" เป็นต้น

ส่วนเสริมของ Classroom

ส่วนเสริมคือ UI และแบ็กเอนด์ที่นักพัฒนาซอฟต์แวร์ให้บริการ ซึ่งมักจะแสดงใน iframe ส่วนเสริมจะปรากฏเป็นไฟล์แนบในรายการสตรีม รายการสตรีมอาจเป็น Announcements, CourseWork หรือ CourseWorkMaterials ส่วนเสริมจะแสดงด้วย AddOnAttachment

ไฟล์แนบของส่วนเสริมอาจเป็นกิจกรรมหรือเนื้อหาก็ได้

• ไฟล์แนบของกิจกรรมกำหนดให้นักเรียนต้องส่งงานแต่ละรายการให้เสร็จสมบูรณ์ ตัวอย่างเช่น แบบทดสอบ ภาพวาด หรือเกม คุณสามารถเลือกให้คะแนนการส่งกิจกรรมได้
• ไฟล์แนบเนื้อหาไม่จำเป็นต้องให้นักเรียนส่ง นักเรียนไม่จำเป็นต้องส่งไฟล์แนบดังกล่าวและระบบจะไม่ให้คะแนนไฟล์แนบ เช่น รูปภาพ บทความ และวิดีโอ

โปรดดูข้อมูลเพิ่มเติมในคู่มือการพัฒนาส่วนเสริม

การลงทะเบียน

แอปพลิเคชันจะสมัครรับการแจ้งเตือนเมื่อมีการเปลี่ยนแปลงข้อมูลบางอย่างใน Google Classroom ได้ เช่น เมื่อมีการอัปเดตบัญชีรายชื่อของหลักสูตร Registrations แสดงคำสั่งให้ส่งการแจ้งเตือนเหล่านี้ไปยังแอปพลิเคชัน

ดูคำแนะนำเกี่ยวกับข้อความ Push เพื่อดูข้อมูลเพิ่มเติม