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

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

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

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

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

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

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

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

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

การแจ้งเตือนจะเข้ารหัสด้วย 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.studentSubmissions จะมีcourseId, courseWorkId และช่อง id ที่ส่งให้แก้ไขไม่ได้ courses.courseWork.studentSubmissions.get()

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

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

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