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

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

บทความนี้ให้ภาพรวมเชิงแนวคิดพร้อมวิธีการง่ายๆ ในการเริ่มรับข้อความ Push

ภาพรวมของข้อความ 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 ในคอนโซลนักพัฒนาแอป (ง่ายที่สุด) ผ่านเครื่องมือบรรทัดคำสั่ง (สำหรับการใช้งานแบบเป็นโปรแกรมที่ไม่ซับซ้อน) หรือใช้ Cloud Pub/Sub โปรดทราบว่า Cloud Pub/Sub อนุญาตหัวข้อเพียงจำนวนหนึ่งเท่านั้น ดังนั้นการใช้หัวข้อเดียวเพื่อรับการแจ้งเตือนทั้งหมดจะช่วยป้องกันไม่ให้เกิดปัญหาในการปรับขนาดหากแอปพลิเคชันได้รับความนิยม

  5. สร้างการสมัครใช้บริการใน Cloud Pub/Sub เพื่อแจ้งให้ Cloud Pub/Sub ทราบวิธีส่งการแจ้งเตือน

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

หมายเหตุ: หากคุณให้สิทธิ์บัญชีบริการข้อความ Push ในการเผยแพร่ไปยังหัวข้อ Cloud Pub/Sub ผู้ใช้ที่ส่งคำขอจากโปรเจ็กต์ Console ของคุณจะระบุได้ว่ามีโปรเจ็กต์อยู่ และลงทะเบียนรับการแจ้งเตือนเกี่ยวกับโปรเจ็กต์นั้นได้ แอปพลิเคชันจำนวนมากจัดเก็บรหัสไคลเอ็นต์ 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() ในทำนองเดียวกัน การเปลี่ยนแปลงในคอลเล็กชัน Course.courseWork จะมีช่อง courseId และ id ที่สามารถส่งได้โดยไม่ต้องแก้ไขไปยัง courses.courseWork.get() และมีการเปลี่ยนแปลงไปที่ courses.courseWork.get().Workcourse has notmission,courses.courses{/2courseIdidcourseWorkIdcourses.courseWork.studentSubmissions.get()

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

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

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