Notifikasi push di Classroom API

Anda dapat menggunakan metode pada koleksi Registrations untuk menerima notifikasi saat data berubah di Classroom.

Artikel ini memberikan ringkasan konseptual beserta petunjuk sederhana tentang cara mulai menerima notifikasi push.

Ringkasan notifikasi push Classroom

Fitur notifikasi push Classroom API memungkinkan aplikasi yang menggunakan Classroom API untuk berlangganan notifikasi saat data berubah di Classroom. Notifikasi dikirim ke topik Cloud Pub/Sub, biasanya dalam beberapa menit setelah perubahan.

Untuk menerima notifikasi push, Anda perlu menyiapkan topik Cloud Pub/Sub dan memberikan nama topik tersebut saat membuat pendaftaran untuk feed notifikasi yang sesuai.

Berikut adalah definisi konsep utama yang digunakan dalam dokumentasi ini:

  • Tujuan adalah tempat notifikasi dikirimkan.
  • Feed adalah jenis notifikasi yang dapat dijadikan langganan aplikasi pihak ketiga. Misalnya, "perubahan daftar nama siswa untuk kursus 1234".
  • Pendaftaran adalah petunjuk ke Classroom API untuk mengirimkan notifikasi dari feed tertentu ke tujuan.

Setelah Anda membuat pendaftaran untuk feed, topik Cloud Pub/Sub pendaftaran tersebut akan menerima notifikasi dari feed tersebut hingga masa berlakunya habis. Pendaftaran Anda berlangsung seminggu, tetapi Anda dapat memperpanjangnya kapan saja sebelum masa berlakunya habis dengan membuat permintaan identik ke registrations.create().

Topik Cloud Pub/Sub Anda hanya menerima notifikasi tentang resource yang dapat Anda lihat dengan kredensial yang Anda berikan saat membuat pendaftaran. Misalnya, jika pengguna mencabut izin dari aplikasi Anda atau dihapus sebagai pengajar, notifikasi akan dikirim lebih lama.

Jenis feed

Classroom API saat ini menawarkan tiga jenis feed:

  • Setiap domain memiliki feed perubahan daftar nama siswa untuk domain, yang menampilkan notifikasi saat siswa dan pengajar bergabung dan keluar dari kursus di domain tersebut.
  • Setiap kursus memiliki feed perubahan daftar nama siswa untuk kursus, yang menampilkan notifikasi saat siswa dan pengajar bergabung dan keluar dari kursus di kursus tersebut.
  • Setiap kursus memiliki feed perubahan tugas untuk mata pelajaran, yang mengekspos notifikasi saat tugas mata pelajaran atau objek kiriman siswa dibuat atau diubah dalam kursus tersebut.

Menyiapkan topik Cloud Pub/Sub

Notifikasi dikirim ke topik Cloud Pub/Sub. Dari Cloud Pub/Sub, Anda dapat menerima notifikasi di hook web atau dengan melakukan polling endpoint langganan.

Untuk menyiapkan topik Cloud Pub/Sub, Anda perlu melakukan hal berikut:

  1. Pastikan Anda memenuhi Prasyarat Cloud Pub/Sub.
  2. Siapkan klien Cloud Pub/Sub.
  3. Tinjau harga Cloud Pub/Sub, dan aktifkan penagihan untuk project Developer Console Anda.

  4. Buat topik Cloud Pub/Sub di Konsol Play (termudah), melalui alat command line (untuk penggunaan terprogram sederhana), atau menggunakan Cloud Pub/Sub API. Perlu diperhatikan bahwa Cloud Pub/Sub hanya mengizinkan topik dalam jumlah terbatas, jadi menggunakan satu topik untuk menerima semua notifikasi akan memastikan Anda tidak mengalami masalah penskalaan jika aplikasi Anda menjadi populer.

  5. Buat Langganan di Cloud Pub/Sub, untuk memberi tahu Cloud Pub/Sub cara mengirimkan notifikasi Anda.

  6. Terakhir, sebelum mendaftar ke Notifikasi Push, Anda perlu memberikan izin akun layanan Notifikasi Push (classroom-notifications@system.gserviceaccount.com) untuk memublikasikan ke topik Anda.

CATATAN: Jika Anda memberikan izin ke akun layanan Notifikasi Push untuk memublikasikan ke topik Cloud Pub/Sub Anda, pengguna yang dapat membuat permintaan dari project Konsol Developer Anda akan dapat menentukan apakah project tersebut ada, dan mendaftar notifikasi. Banyak aplikasi menyimpan Client ID OAuth di sisi klien, sehingga pengguna akhir mungkin dapat membuat permintaan dari project Konsol Developer Anda. Jika ini terjadi, dan Anda khawatir pengguna akhir mengirim notifikasi yang tidak diinginkan ke topik Cloud Pub/Sub Anda atau mengetahui nama topik Cloud Pub/Sub yang Anda gunakan untuk notifikasi push, sebaiknya pertimbangkan untuk mendaftar ke notifikasi push dari project Konsol Play lain.

Daftarkan aplikasi Anda untuk notifikasi

Setelah memiliki topik yang dapat dipublikasikan oleh akun layanan notifikasi push Classroom API, Anda dapat mendaftar untuk notifikasi, menggunakan metode registrations.create(). Metode registrations.create() memvalidasi bahwa topik Cloud/Pub Cloud yang disediakan dapat dijangkau oleh akun layanan notifikasi push. Metode ini akan gagal jika akun layanan notifikasi push tidak dapat menjangkau topik; misalnya, jika topik tidak ada atau Anda belum memberikan izin publikasi untuk topik tersebut.

Otorisasi

Seperti semua panggilan ke Classroom API, panggilan ke registrations.create() harus diotorisasi dengan token otorisasi. Token autentikasi ini harus menyertakan cakupan Notifikasi Push (https://www.googleapis.com/auth/classroom.push-notifications) dan cakupan apa pun yang diperlukan untuk melihat data tentang notifikasi yang dikirimkan.

  • Untuk feed perubahan daftar nama siswa, ini berarti cakupan Rosters atau (idealnya) varian hanya baca (https://www.googleapis.com/auth/classroom.rosters.readonly atau https://www.googleapis.com/auth/classroom.rosters).
  • Untuk feed perubahan tugas kursus, ini berarti versi "siswa" dari cakupan pekerjaan kursus atau (idealnya) varian hanya baca (https://www.googleapis.com/auth/classroom.coursework.students.readonly atau https://www.googleapis.com/auth/classroom.coursework.students).

Agar notifikasi dapat dikirim, aplikasi harus mempertahankan pemberian izin OAuth dari pengguna yang diotorisasi dengan cakupan yang diperlukan. Jika pengguna memutuskan aplikasi, notifikasi akan berhenti. Perhatikan bahwa saat ini, delegasi tingkat domain tidak didukung untuk tujuan ini. Jika mencoba mendaftar untuk notifikasi hanya menggunakan otoritas yang didelegasikan di seluruh domain, Anda akan menerima error `@MissingGrant.

Menerima notifikasi

Notifikasi dienkode dengan JSON, dan berisi:

  • Nama koleksi yang berisi resource yang berubah. Untuk notifikasi tentang perubahan daftar nama siswa, notifikasi ini dapat berupa courses.students atau courses.teachers. Untuk perubahan tugas kursus, ini adalah courses.courseWork atau courses.courseWork.studentSubmissions.
  • ID untuk resource yang berubah, di peta. Peta ini dirancang untuk mencocokkan argumen dengan metode get resource yang sesuai. Untuk notifikasi tentang perubahan daftar nama siswa, kolom courseId dan userId akan diisi, dan dapat dikirim tanpa diubah ke courses.students.get() atau courses.teachers.get(). Demikian pula, perubahan pada koleksi kursus.courseWork akan memiliki kolom courseId dan id yang dapat dikirim tanpa perubahan ke courses.courseWork.get() dan perubahan ke kolom kursus.coursesmission subjek.tugas.ditujukan)

Cuplikan kode berikut menunjukkan contoh notifikasi:

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

Notifikasi juga memiliki atribut pesan registrationId, yang berisi ID pendaftaran yang menyebabkan notifikasi, yang dapat digunakan dengan registrations.delete() untuk membatalkan pendaftaran dari notifikasi.