บทนำ

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

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

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

ก่อนที่จะเจาะลึกรายละเอียดทางเทคนิคเกี่ยวกับลักษณะของการผสานรวมการนำเข้าบัญชีรายชื่อ เรามาดูเวิร์กโฟลว์ตัวอย่างกันก่อน

1. ในแอปพลิเคชันของบุคคลที่สาม ครูเลือกตัวเลือกเพื่อนำเข้าหลักสูตร Classroom Course

2. แอปพลิเคชันของบุคคลที่สามเรียกใช้เมธอด courses.list ผ่าน Classroom API ซึ่งจะแสดงผลการตอบสนอง JSON ที่มีหลักสูตรทั้งหมดของครู

3. จากผลการตอบสนอง JSON แอปพลิเคชันของบุคคลที่สามจะแสดงชื่อหลักสูตรของครูเพื่อให้ครูเลือกหลักสูตรที่ต้องการ แอปพลิเคชันจะต้องติดตามรหัสหลักสูตรเพื่อดำเนินการต่อในขั้นตอนถัดไป

4. แอปพลิเคชันของบุคคลที่สามเรียกใช้เมธอด students.list และ teachers.list ด้วยรหัสหลักสูตรที่เลือก แล้วแสดงชื่อทั้งหมดในเว็บไซต์เพื่อให้ครูยืนยันการนำเข้า

5. แอปพลิเคชันของบุคคลที่สามเชิญผู้ใช้ให้เข้าร่วมหลักสูตรที่นำเข้าใหม่ในแพลตฟอร์มของตนเองโดยใช้อีเมลที่แสดงผลใน JSON การตอบสนองของ students.list และ teachers.list

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

1. จัดการหลักสูตรด้วย Classroom API
2. จัดการนักเรียนและครู

นอกจากแผนภาพเวิร์กโฟลว์ด้านล่างแล้ว โปรดดู ตัวอย่างจริงของ ActivelyLearn เพื่อให้เข้าใจการผสานรวมประเภทนี้ได้ดียิ่งขึ้น

เริ่มต้นใช้งาน

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

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

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

การใช้การแจ้งเตือนแบบพุชจะต้องมีขอบเขตเพิ่มเติม 1 รายการ ซึ่งคุณไม่จำเป็นต้องส่งเพื่อรับการยืนยัน

• https://www.googleapis.com/auth/classroom.push-notifications
  • อนุญาตให้แอปของคุณลงทะเบียนเพื่อรับกิจกรรมการแจ้งเตือนแบบพุช

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