ข้อความ 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 คุณจะรับการแจ้งเตือนในเว็บฮุก หรือโดยการสำรวจปลายทางการสมัครรับข้อมูลได้

หากต้องการตั้งค่าหัวข้อ 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 Pub/Sub เพื่อบอก Cloud Pub/Sub ว่าจะส่งการแจ้งเตือนอย่างไร

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

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

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

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

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

การเรียก 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() เพื่อยกเลิกการลงทะเบียนจากการแจ้งเตือนได้