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

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

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

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

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

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

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

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

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

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

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

Classroom API มีฟีด 3 ประเภท ได้แก่

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

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

ระบบจะส่งการแจ้งเตือนไปยังหัวข้อ Cloud Pub/Sub คุณสามารถรับการแจ้งเตือนใน Webhook หรือโดยการสำรวจปลายทางการสมัครรับข้อมูลจาก 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. สุดท้ายนี้ ก่อนลงทะเบียนรับการแจ้งเตือนแบบพุช คุณต้องให้สิทธิ์ บัญชีบริการการแจ้งเตือนแบบพุช (classroom-notifications@system.gserviceaccount.com)ในการ เผยแพร่ไปยังหัวข้อของคุณ

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

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

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

เช่นเดียวกับการเรียกไปยัง Classroom API ทั้งหมด การเรียกไปยัง registrations.create() ต้องได้รับอนุญาตด้วยโทเค็นการให้สิทธิ์ โทเค็นการตรวจสอบสิทธิ์นี้ต้องมีขอบเขตการแจ้งเตือนแบบพุช (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() เพื่อยกเลิกการลงทะเบียนรับการแจ้งเตือน