แหล่งข้อมูล API

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

นักเรียน/นักศึกษาจะได้รับอนุญาตให้ดูรายละเอียดหลักสูตรและครูของหลักสูตรนั้น

ครู

Teacher ทรัพยากรแสดงถึงผู้ใช้ที่สอนหลักสูตรใดหลักสูตรหนึ่ง

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

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

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

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

ดูข้อมูลเพิ่มเติมเกี่ยวกับการจัดการรายชื่อได้ที่จัดการครูและนักเรียน/นักศึกษา

สตรีมรายการ

รายการในสตรีมคือเนื้อหาที่โพสต์และแชร์กับสมาชิกของหลักสูตร นักพัฒนาแอปและครูสามารถสร้างรายการในสตรีมได้ 3 ประเภท ได้แก่ Announcement CourseWork และ CourseWorkMaterial

ครูสร้างAnnouncementsที่ด้านบนของหน้าสตรีมใน UI ของ Classroom ครูสร้าง CourseWork และ CourseWorkMaterials โดยคลิกปุ่มสร้างในแท็บงานของชั้นเรียน นักพัฒนาแอปสามารถสร้างรายการสตรีมทุกประเภทโดยใช้โปรแกรมผ่าน Classroom API

รายการในสตรีมมีลักษณะดังนี้

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

คัดลอกรายการสตรีมแล้ว

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

CourseWork และ StudentSubmissions

CourseWork รายการแสดงถึงงานสำหรับกลุ่มนักเรียน/นักศึกษาใน หลักสูตร ซึ่งเป็นประเภทรายการในสตรีมเดียวที่รับงานที่นักเรียนส่งได้ CourseWorkทรัพยากรมีรายละเอียดต่างๆ เช่น คำอธิบาย วันที่ครบกำหนด คะแนนสูงสุด และข้อมูลเมตา เช่น เวลาที่สร้าง

CourseWorkแต่ละแหล่งข้อมูลจะอธิบายงานประเภทใดประเภทหนึ่งต่อไปนี้

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

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

เนื้อหาของ StudentSubmission จะขึ้นอยู่กับประเภทของรายการที่เกี่ยวข้อง CourseWork และอาจรวมถึงข้อมูลต่อไปนี้

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

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

CourseWorkMaterials และ Announcements

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

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

หัวข้อ

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

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

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

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

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

ดูข้อมูลเพิ่มเติมได้ที่คำแนะนำในการพัฒนาส่วนเสริม

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

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

ดูข้อมูลเพิ่มเติมได้ที่คู่มือการแจ้งเตือนแบบพุช