ครูที่ใช้ทั้ง Classroom และเครื่องมือของบุคคลที่สามต้องเผชิญกับความท้าทายในการตั้งค่าหลักสูตรและบัญชีรายชื่อในหลายแพลตฟอร์ม ซึ่งอาจทำได้ด้วยตนเอง ไม่ว่าจะผ่านการอัปโหลด CSV หรือการป้อนอีเมลทีละรายการ อย่างไรก็ตาม Classroom API ช่วยให้เครื่องมือของบุคคลที่สามลดภาระงานของครูได้โดยการผสานรวมกับ Use Case ที่พบบ่อยที่สุดของ API ซึ่งก็คือการนำเข้ารายชื่อ
การนำเข้าบัญชีรายชื่อช่วยให้แพลตฟอร์มของบุคคลที่สามดึงข้อมูลเมตาของหลักสูตร ครู และนักเรียนในแต่ละหลักสูตรได้โดยมีสิทธิ์ของครูหรือ ผู้ดูแลระบบ ครูจะดึงรายละเอียดของหลักสูตรที่สอนได้ ส่วนผู้ดูแลระบบจะเข้าถึงรายละเอียดของหลักสูตรทั้งหมดในโดเมนทั้งโดเมนได้ ความยืดหยุ่นนี้ช่วยให้นักพัฒนาแอปสามารถเริ่มต้นใช้งาน บัญชีรายชื่อใน Classroom บนแพลตฟอร์มของตนได้อย่างราบรื่น ไม่ว่าจะเป็นในระดับครูแต่ละคนหรือ ทั่วทั้งโดเมนโดยใช้ข้อมูลเข้าสู่ระบบของผู้ดูแลระบบ
ก่อนที่จะเจาะลึกรายละเอียดทางเทคนิคของลักษณะการผสานรวมการนำเข้ารายชื่อ เรามาดูตัวอย่างเวิร์กโฟลว์กันก่อน
ในแอปพลิเคชันของบุคคลที่สาม ครูเลือกตัวเลือกเพื่อนำเข้าหลักสูตรของ Classroom
แอปพลิเคชันของบุคคลที่สามจะเรียกใช้เมธอด
courses.listผ่าน Classroom API ซึ่งจะแสดงผล JSON การตอบกลับพร้อมหลักสูตรทั้งหมดของครูจากคำตอบของ JSON แอปพลิเคชันของบุคคลที่สามจะแสดงชื่อหลักสูตรของครูเพื่อให้ครูเลือกหลักสูตร แอปพลิเคชันจะต้องติดตามรหัสหลักสูตรเพื่อไปยังขั้นตอนถัดไป
เมื่อเลือกรหัสหลักสูตรแล้ว แอปพลิเคชันของบุคคลที่สามจะเรียกใช้เมธอด
students.listและteachers.listและแสดงชื่อทั้งหมดในเว็บไซต์เพื่อให้ครูยืนยันการนำเข้าแอปพลิเคชันของบุคคลที่สามจะใช้อีเมลที่ส่งคืนใน JSON ของการตอบกลับ
students.listและteachers.listเพื่อเชิญผู้ใช้ให้เข้าร่วมหลักสูตรที่เพิ่งนำเข้าใหม่ในแพลตฟอร์มของตน
สำหรับแต่ละวิธีที่กล่าวถึงในเวิร์กโฟลว์ คุณสามารถใช้ API Explorer เพื่อดูว่าแต่ละวิธีทำงานอย่างไร นอกจากนี้ เราขอแนะนำให้คุณอ่านข้อมูลต่อไปนี้ ก่อนที่จะอ่านคำแนะนำนี้จนจบ
เริ่มต้นใช้งาน
ก่อนที่จะนำรายละเอียดการนำเข้าบัญชีรายชื่อของ Classroom ไปใช้ คุณจะต้อง พิจารณาว่าคุณจะต้องดึงข้อมูลหลักสูตรและผู้ใช้ใดผ่าน API คุณดูข้อมูลเมตาของหลักสูตรที่มีได้ใน เอกสารอ้างอิง แต่เราจะสรุปช่องที่จำเป็นหรือช่องทั่วไปที่ต้องใช้ไว้ด้านล่าง
| ช่อง | ใช้ |
|---|---|
| id | ต้องระบุสำหรับคำขอ API ที่ดึงข้อมูลนักเรียนหรือครู |
| ชื่อ | แนะนำเพื่อความสะดวกในการใช้งานสำหรับผู้ใช้ เช่น การแสดงบนเว็บไซต์ |
| ownerId | ต้องระบุเมื่อนำเข้าทั้งโดเมนเพื่อระบุ ครูผู้สอนหลักของหลักสูตรอย่างถูกต้อง |
ระบบจะดึงข้อมูลหลักสูตรนี้ในcourses.listขั้นตอนของเวิร์กโฟลว์
ด้านบน ในคำขอนี้ คุณสามารถระบุพารามิเตอร์คำขอที่ต้องการได้ แม้ว่าวิธีนี้จะไม่จำเป็น แต่พารามิเตอร์ที่แนะนำมีดังนี้
| พารามิเตอร์ | ใช้ |
|---|---|
| courseState | หากไม่ได้ระบุ API จะแสดงหลักสูตรที่มี สถานะหลักสูตรทั้ง 6 สถานะ เราขอแนะนำให้ระบุ ACTIVE เพื่อดึงข้อมูลหลักสูตรที่ครูกำลังใช้อยู่ |
| pageSize | สำหรับครูที่นำเข้าหลักสูตรของตนเอง เราขอแนะนำให้ระบุ pageSize ขนาดเล็ก (น้อยกว่า 10) เพื่อลดเวลาตอบสนองของการเรียก API |
| pageToken | ต้องระบุหากคุณใช้คำขอแบบแบ่งหน้า |
| teacherId | แนะนำเนื่องจากผู้ดูแลระบบโดเมนมักจะสอนหลักสูตร หากไม่ได้ระบุ ระบบจะแสดงหลักสูตรสำหรับครูทั่วทั้งโดเมน |
| Fields | ขอแนะนำให้ลดเวลาตอบกลับของการเรียก API |
ตอนนี้แอปพลิเคชันของคุณสามารถดึงข้อมูล
รายชื่อนักเรียนและครูร่วมสอนสำหรับหลักสูตรนั้นๆ โดยใช้รหัสหลักสูตรที่ดึงข้อมูลมาก่อนหน้านี้ รหัสหลักสูตรนี้เป็นพารามิเตอร์การค้นหาที่จำเป็นเพียงรายการเดียวสำหรับ teachers.list และ students.list แต่คุณอาจต้องการระบุพารามิเตอร์ pageSize และ fields ในลักษณะเดียวกันเพื่อลดเวลาในการตอบกลับของการเรียก API
ดูฟิลด์ทั้งหมดที่ใช้ได้สำหรับแหล่งข้อมูลของนักเรียน
และครู
ได้ในเอกสารประกอบที่เกี่ยวข้อง ฟิลด์ที่ใช้บ่อยที่สุด 2 ฟิลด์และมักจะต้องระบุคือฟิลด์ profile
profile.name และ profile.emailAddress
| ช่อง | ใช้ |
|---|---|
| profile.name | แนะนำเพื่อความสะดวกในการใช้งานสำหรับผู้ใช้ เช่น การแสดงบนเว็บไซต์ |
| profile.emailAddress | ต้องระบุสำหรับแอปพลิเคชันที่ต้องการระบุนักเรียนที่ไม่ซ้ำกัน |
หากต้องการดึงและใช้รายละเอียดหลักสูตรหรือรายชื่อใดๆ เหล่านี้จาก Classroom แอปพลิเคชันของคุณจะต้องขอการให้สิทธิ์จากผู้ใช้ เวิร์กโฟลว์นี้ต้องใช้ขอบเขต 3 รายการต่อไปนี้
- https://www.googleapis.com/auth/classroom.courses.readonly
- ให้สิทธิ์เข้าถึงแบบอ่านอย่างเดียวสำหรับหลักสูตรใน Google Classroom
- https://www.googleapis.com/auth/classroom.rosters.readonly
- ให้สิทธิ์เข้าถึงแบบอ่านอย่างเดียวแก่บัญชีรายชื่อของหลักสูตร Google Classroom (ครูและนักเรียน)
- https://www.googleapis.com/auth/classroom.profile.emails
- ให้สิทธิ์การอ่านพร็อพเพอร์ตี้อีเมลของครูและนักเรียน
ซิงค์บัญชีรายชื่อกับการแจ้งเตือน Pub/Sub
เมื่อปีการศึกษาดำเนินไป บัญชีรายชื่ออาจเปลี่ยนแปลงเมื่อนักเรียนลงทะเบียนหรือยกเลิกการลงทะเบียน หลักสูตร การเพิ่มการแจ้งเตือน Pub/Sub จะช่วยให้คุณซิงค์แอปพลิเคชันของบุคคลที่สามกับบัญชีรายชื่อของ Classroom ได้ หากต้องการรับการแจ้งเตือน คุณต้องตั้งค่าหัวข้อ Google Cloud Pub/Sub แล้วลงทะเบียนหัวข้อกับ Classroom API การลงทะเบียนนี้เป็นการขอให้ Classroom ส่งข้อมูลจากฟีดที่ระบุไปยังหัวข้อที่ระบุ ฟีดนี้จะเป็นทริกเกอร์เหตุการณ์สำหรับการซิงค์บัญชีรายชื่อของชั้นเรียนกับบัญชีรายชื่อของครูอีกครั้ง
การใช้ประโยชน์จากข้อความพุชจะต้องมีขอบเขตเพิ่มเติม 1 รายการ ซึ่งไม่จำเป็นต้องส่งเพื่อรับการยืนยัน
- https://www.googleapis.com/auth/classroom.push-notifications
- อนุญาตให้แอปของคุณลงทะเบียนสำหรับกิจกรรมการแจ้งเตือนแบบพุช
ดูรายละเอียดเพิ่มเติมเกี่ยวกับวิธีผสานรวมกับการแจ้งเตือนแบบพุชของ Classroom ได้ในคู่มือการจัดการการแจ้งเตือนแบบพุช