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