แนะนำตัว

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

ดูช่องทั้งหมดที่มีสำหรับแหล่งข้อมูล ของนักเรียน และครูได้ในเอกสารที่เกี่ยวข้อง ช่อง 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

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