บทนำ

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

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

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

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

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

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

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

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

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

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

แผนภาพที่สรุปเวิร์กโฟลว์การนําเข้าข้อมูลผู้เล่นที่อธิบายไว้ข้างต้น

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

ก่อนใช้ข้อมูลเฉพาะของการนำเข้าข้อมูลบัญชีผู้ใช้ใน 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
    • ให้สิทธิ์การอ่านพร็อพเพอร์ตี้ email ของครูและนักเรียน

ซิงค์บัญชีรายชื่อกับการแจ้งเตือน Pub/Sub

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

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

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

แผนภาพที่สรุปเวิร์กโฟลว์การนําเข้าข้อมูลผู้เล่นด้วยข้อความ Push

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