ข้อความ Push ใน Classroom API

คุณสามารถใช้เมธอดในคอลเล็กชัน Registrations เพื่อรับการแจ้งเตือนเมื่อมีการเปลี่ยนแปลงข้อมูลใน Classroom

บทความนี้จะอธิบายภาพรวมเชิงแนวคิดพร้อมวิธีการง่ายๆ ในการเริ่มรับการแจ้งเตือนแบบพุช

ภาพรวมของข้อความ Push ของ Classroom

ฟีเจอร์ข้อความ Push ของ Classroom API ช่วยให้แอปพลิเคชันที่ใช้ Classroom API สามารถสมัครรับการแจ้งเตือนเมื่อมีการเปลี่ยนแปลงข้อมูลใน Classroom ระบบจะส่งการแจ้งเตือนไปยังหัวข้อ Cloud Pub/Sub โดยปกติภายในไม่กี่นาทีหลังจากการเปลี่ยนแปลง

หากต้องการรับข้อความ Push คุณต้องตั้งค่าหัวข้อ Cloud Pub/Sub และระบุชื่อหัวข้อนั้นเมื่อสร้างการลงทะเบียนสําหรับฟีดการแจ้งเตือนที่เหมาะสม

คําจํากัดความของแนวคิดหลักที่ใช้ในเอกสารประกอบมีดังนี้

  • ปลายทางคือตำแหน่งที่ระบบจะส่งการแจ้งเตือน
  • ฟีดคือการแจ้งเตือนประเภทหนึ่งที่แอปพลิเคชันของบุคคลที่สามสามารถสมัครรับข้อมูลได้ เช่น "การเปลี่ยนแปลงบัญชีรายชื่อสำหรับหลักสูตร 1234"
  • การลงทะเบียนคือคำสั่งให้ Classroom API ส่งการแจ้งเตือนจากฟีดหนึ่งไปยังปลายทาง

เมื่อคุณสร้างการลงทะเบียนฟีดแล้ว หัวข้อ Cloud Pub/Sub ของการลงทะเบียนดังกล่าวจะได้รับการแจ้งเตือนจากฟีดนั้นจนกว่าจะหมดอายุ การลงทะเบียนจะมีอายุ 1 สัปดาห์ แต่คุณขยายเวลาได้ทุกเมื่อก่อนที่การลงทะเบียนจะหมดอายุโดยส่งคำขอที่เหมือนกับ registrations.create()

หัวข้อ Cloud Pub/Sub ของคุณจะได้รับการแจ้งเตือนเกี่ยวกับทรัพยากรที่คุณดูได้ด้วยข้อมูลเข้าสู่ระบบที่ระบุไว้เมื่อสร้างการลงทะเบียนเท่านั้น เช่น หากผู้ใช้เพิกถอนสิทธิ์จากแอปพลิเคชันของคุณหรือถูกนำออกจากการเป็นครู ระบบจะไม่ส่งการแจ้งเตือนอีกต่อไป

ประเภทของฟีด

ปัจจุบัน Classroom API มีฟีด 3 ประเภท ได้แก่

  • โดเมนแต่ละโดเมนจะมีฟีดการเปลี่ยนแปลงข้อมูลรายชื่อสำหรับโดเมน ซึ่งจะแสดงการแจ้งเตือนเมื่อนักเรียนและครูเข้าร่วมและออกจากหลักสูตรในโดเมนนั้น
  • แต่ละหลักสูตรจะมีฟีดการเปลี่ยนแปลงข้อมูลสำหรับหลักสูตร ซึ่งจะแสดงการแจ้งเตือนเมื่อนักเรียนและครูเข้าร่วมและออกจากหลักสูตรนั้น
  • แต่ละหลักสูตรจะมีฟีดการเปลี่ยนแปลงงานในหลักสูตรสำหรับหลักสูตร ซึ่งจะแสดงการแจ้งเตือนเมื่อมีการสร้างหรือแก้ไขงานในหลักสูตรหรือออบเจ็กต์งานที่นักเรียนส่งในหลักสูตรนั้น

การตั้งค่าหัวข้อ Cloud Pub/Sub

ระบบจะส่งการแจ้งเตือนไปยังหัวข้อ Cloud Pub/Sub จาก Cloud Pub/Sub คุณจะได้รับการแจ้งเตือนใน Webhook หรือโดยการพูลข้อมูลปลายทางการสมัครใช้บริการ

หากต้องการตั้งค่าหัวข้อ Cloud Pub/Sub คุณต้องทําดังนี้

  1. ตรวจสอบว่าคุณมีคุณสมบัติตรงตามข้อกําหนดเบื้องต้นของ Cloud Pub/Sub
  2. ตั้งค่าไคลเอ็นต์ Cloud Pub/Sub
  3. ตรวจสอบราคาของ Cloud Pub/Sub และเปิดใช้การเรียกเก็บเงินสำหรับโปรเจ็กต์ใน Developer Console

  4. สร้างหัวข้อ Cloud Pub/Sub ใน Developer Console (วิธีที่ง่ายที่สุด) ผ่านเครื่องมือบรรทัดคำสั่ง (สำหรับการใช้งานแบบเป็นโปรแกรมอย่างง่าย) หรือใช้ Cloud Pub/Sub API โปรดทราบว่า Cloud Pub/Sub อนุญาตหัวข้อได้จํากัด ดังนั้นการใช้หัวข้อเดียวเพื่อรับการแจ้งเตือนทั้งหมดจะช่วยให้คุณไม่พบปัญหาการปรับขนาดหากแอปพลิเคชันได้รับความนิยม

  5. สร้างการสมัครใช้บริการใน Cloud Publi/Sub เพื่อบอก Cloud Publi/Sub ว่าจะส่งการแจ้งเตือนอย่างไร

  6. สุดท้าย ก่อนลงทะเบียนเพื่อรับ Push Notifications คุณต้องให้สิทธิ์บัญชีบริการ Push Notifications (classroom-notifications@system.gserviceaccount.com) เพื่อเผยแพร่ไปยังหัวข้อ

หมายเหตุ: หากคุณให้สิทธิ์บัญชีบริการ Push Notifications เผยแพร่ไปยังหัวข้อ Cloud Pub/Sub ผู้ใช้ที่ส่งคำขอจากโปรเจ็กต์คอนโซลของนักพัฒนาแอปจะทราบว่าหัวข้อดังกล่าวมีอยู่และลงทะเบียนรับการแจ้งเตือนจากหัวข้อนั้นได้ แอปพลิเคชันจำนวนมากจัดเก็บรหัสไคลเอ็นต์ OAuth ไว้ฝั่งไคลเอ็นต์ ดังนั้นผู้ใช้ปลายทางจึงอาจส่งคำขอจากโปรเจ็กต์ใน Developer Console ได้ หากคุณอยู่ในสถานการณ์นี้และกังวลว่าผู้ใช้ปลายทางจะส่งการแจ้งเตือนที่ไม่ต้องการไปยังหัวข้อ Cloud Pub/Sub หรือทราบชื่อหัวข้อ Cloud Pub/Sub ที่คุณใช้สำหรับ Push Notifications คุณควรพิจารณาลงทะเบียนรับ Push Notifications จากโปรเจ็กต์คอนโซลของนักพัฒนาแอปอื่น

ลงทะเบียนแอปพลิเคชันเพื่อรับการแจ้งเตือน

เมื่อคุณมีหัวข้อที่บัญชีบริการข้อความ Push ของ Classroom API เผยแพร่ได้ คุณจะลงทะเบียนรับการแจ้งเตือนได้โดยใช้เมธอด registrations.create() เมธอด registrations.create() จะตรวจสอบว่าบัญชีบริการ Push Notification สามารถเข้าถึงหัวข้อ Cloud Pub/Sub ที่ระบุได้ วิธีการจะดำเนินการไม่สำเร็จหากบัญชีบริการ Push Notification เข้าถึงหัวข้อไม่ได้ เช่น หัวข้อนั้นไม่มีอยู่หรือคุณยังไม่ได้ให้สิทธิ์เผยแพร่ในหัวข้อนั้น

การให้สิทธิ์

การเรียก registrations.create() ต้องได้รับการให้สิทธิ์ด้วยโทเค็นการให้สิทธิ์ เช่นเดียวกับการเรียกใช้ Classroom API ทั้งหมด โทเค็นการตรวจสอบสิทธิ์นี้ต้องมีขอบเขตข้อความ Push (https://www.googleapis.com/auth/classroom.push-notifications) และขอบเขตอื่นๆ ที่จําเป็นในการดูข้อมูลเกี่ยวกับการแจ้งเตือนที่ส่ง

  • สำหรับฟีดการเปลี่ยนแปลงข้อมูลผู้เล่น หมายถึงขอบเขต "ข้อมูลผู้เล่น" หรือ (ตามหลักการแล้ว) ตัวแปรที่อ่านอย่างเดียวของข้อมูลผู้เล่น (https://www.googleapis.com/auth/classroom.rosters.readonly หรือ https://www.googleapis.com/auth/classroom.rosters)
  • สำหรับฟีดการเปลี่ยนแปลงงานในหลักสูตร หมายความว่าขอบเขตงานในหลักสูตรเวอร์ชัน "นักเรียน" หรือ (ตามหลักการแล้ว) ตัวแปรที่อ่านอย่างเดียว (https://www.googleapis.com/auth/classroom.coursework.students.readonly หรือ https://www.googleapis.com/auth/classroom.coursework.students)

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

การรับการแจ้งเตือน

การแจ้งเตือนจะเข้ารหัสด้วย JSON และมีข้อมูลต่อไปนี้

  • ชื่อคอลเล็กชันที่มีทรัพยากรที่เปลี่ยนแปลง สําหรับการแจ้งเตือนเกี่ยวกับการเปลี่ยนแปลงบัญชีรายชื่อ จะเป็น courses.students หรือ courses.teachers สำหรับการเปลี่ยนแปลงงานในหลักสูตร ตัวเลือกจะเป็น courses.courseWork หรือ courses.courseWork.studentSubmissions
  • ตัวระบุของทรัพยากรที่มีการเปลี่ยนแปลงในแผนที่ แผนที่นี้ออกแบบมาเพื่อจับคู่อาร์กิวเมนต์กับเมธอด get ของทรัพยากรที่เหมาะสม สําหรับการแจ้งเตือนเกี่ยวกับการเปลี่ยนแปลงบัญชีรายชื่อ ฟิลด์ courseId และ userId จะสร้างขึ้นและสามารถส่งไปยัง courses.students.get() หรือ courses.teachers.get() โดยไม่ต้องแก้ไข ในทํานองเดียวกัน การเปลี่ยนแปลงในคอลเล็กชัน courses.courseWork จะมีฟิลด์ courseId และ id ที่ส่งไปยัง courses.courseWork.get() โดยไม่ต้องแก้ไขได้ และการเปลี่ยนแปลงในคอลเล็กชัน courses.courseWork.studentSubmissions จะมีฟิลด์ courseId, courseWorkId และ id ที่ส่งไปยัง courses.courseWork.studentSubmissions.get() โดยไม่ต้องแก้ไขได้

ข้อมูลโค้ดต่อไปนี้แสดงตัวอย่างการแจ้งเตือน

{
  "collection": "courses.students",
  "eventType": "CREATED",
  "resourceId": {
    "courseId": "12345",
    "userId": "45678"
  }
}

การแจ้งเตือนยังมีแอตทริบิวต์ข้อความ registrationId ซึ่งมีตัวระบุสำหรับการลงทะเบียนที่ทําให้การแจ้งเตือนเกิดขึ้น ซึ่งสามารถใช้ร่วมกับ registrations.delete() เพื่อยกเลิกการลงทะเบียนจากการแจ้งเตือน