ครูที่ใช้ประโยชน์จากทั้ง Classroom และเครื่องมือของบุคคลที่สามเผชิญกับความท้าทายในการตั้งค่าหลักสูตรและบัญชีรายชื่อในหลายแพลตฟอร์ม ซึ่งอาจดำเนินการด้วยตนเอง โดยใช้การอัปโหลดไฟล์ CSV หรือป้อนอีเมลทีละรายการ แต่หากใช้ Classroom API เครื่องมือของบุคคลที่สามจะช่วยลดภาระงานของครูได้ด้วยการผสานรวมกับกรณีการใช้งานที่พบบ่อยที่สุดของ API ซึ่งก็คือการนำเข้าบัญชีรายชื่อ
การนำเข้าบัญชีรายชื่อช่วยให้แพลตฟอร์มของบุคคลที่สามเรียกข้อมูลเมตาของหลักสูตร ครู และนักเรียนของหลักสูตรได้แบบทีละหลักสูตรโดยใช้สิทธิ์ของครูหรือผู้ดูแลระบบ ครูจะเรียกดูรายละเอียดของหลักสูตรที่สอนได้ ขณะที่ผู้ดูแลระบบจะเข้าถึงรายละเอียดของหลักสูตรทั้งหมดในทั้งโดเมนได้ ความยืดหยุ่นนี้ช่วยให้นักพัฒนาซอฟต์แวร์เริ่มต้นใช้งานบัญชีรายชื่อ Classroom บนแพลตฟอร์มของตนได้อย่างราบรื่นทั้งในระดับครูเป็นรายบุคคลหรือทั่วทั้งโดเมนโดยใช้ข้อมูลเข้าสู่ระบบของผู้ดูแลระบบ
ก่อนที่จะเจาะลึกรายละเอียดทางเทคนิคของการผสานรวมการนำเข้าบัญชีรายชื่อ เรามาทบทวนเวิร์กโฟลว์ตัวอย่างกันก่อน
ครูเลือกตัวเลือกเพื่อนำเข้าหลักสูตรของ Classroom ในแอปพลิเคชันของบุคคลที่สาม
แอปพลิเคชันของบุคคลที่สามจะเรียกเมธอด
courses.list
ผ่าน Classroom API ซึ่งจะแสดง JSON ของการตอบกลับที่มีหลักสูตรทั้งหมดของครูจากการตอบกลับ JSON แอปพลิเคชันของบุคคลที่สามจะแสดงชื่อของหลักสูตรของครูให้นักเรียนเลือก ใบสมัครจะต้องติดตามรหัสหลักสูตรเพื่อดำเนินการต่อไปยังขั้นตอนถัดไป
แอปพลิเคชันของบุคคลที่สามจะเรียกใช้เมธอด
students.list
และteachers.list
โดยใช้รหัสหลักสูตรที่เลือก และแสดงชื่อทั้งหมดบนเว็บไซต์เพื่อให้ครูยืนยันเพื่อนำเข้าได้แอปพลิเคชันของบุคคลที่สามได้ใช้อีเมลที่แสดงผลใน JSON การตอบกลับ
students.list
และteachers.list
เพื่อเชิญผู้ใช้ให้เข้าร่วมหลักสูตรที่นำเข้าใหม่บนแพลตฟอร์มของตน
สำหรับแต่ละเมธอดที่กล่าวถึงในเวิร์กโฟลว์ คุณสามารถใช้โปรแกรมสำรวจ API เพื่อดูการทำงานของแต่ละวิธีได้ นอกจากนี้ เราขอแนะนำให้อ่านข้อมูลต่อไปนี้ล่วงหน้าก่อนที่จะจบคู่มือนี้
เริ่มต้นใช้งาน
ก่อนที่จะใช้การนำเข้าบัญชีรายชื่อใน 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
ดูช่องทั้งหมดที่มีสำหรับแหล่งข้อมูล
ของนักเรียน
และครูได้ในเอกสารที่เกี่ยวข้อง ช่อง 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 ของครูอีกครั้ง
การใช้ข้อความ Push จะต้องมีขอบเขตเพิ่มเติม 1 ขอบเขต ซึ่งไม่จำเป็นต้องส่งเพื่อขอรับการยืนยัน
- https://www.googleapis.com/auth/classroom.push-notifications
- อนุญาตให้แอปลงทะเบียนสำหรับกิจกรรมข้อความ Push
โปรดดูรายละเอียดเพิ่มเติมเกี่ยวกับวิธีผสานรวมกับข้อความ Push ของ Classroom ที่คู่มือจัดการข้อความ Push