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

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

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

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

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

CourseWorkMaterials and Announcements

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 Notification