Add-on Google Classroom kini tersedia secara umum untuk developer. Lihat dokumentasi add-on untuk informasi selengkapnya.

Halaman ini diterjemahkan oleh Cloud Translation API.

Notifikasi push di Classroom API

Anda dapat menggunakan metode pada kumpulan 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 harus 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 dikirim.
Feed adalah jenis notifikasi yang dapat diikuti oleh aplikasi pihak ketiga. Misalnya, "perubahan daftar pemain 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 selama seminggu, tetapi Anda dapat memperpanjangnya kapan saja sebelum masa berlakunya berakhir dengan membuat permintaan yang identik dengan 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 tidak akan dikirim lagi.

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 serta keluar dari kursus di kursus tersebut.
Setiap kursus memiliki feed perubahan tugas kursus untuk kursus, yang menampilkan notifikasi saat objek tugas kursus atau kiriman siswa dibuat atau diubah di 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 pada endpoint langganan.

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

Pastikan Anda memenuhi Prasyarat Cloud Pub/Sub.
Menyiapkan klien Cloud Pub/Sub.
Tinjau harga Cloud Pub/Sub, dan aktifkan penagihan untuk project Developer Console Anda.
Buat topik Cloud Pub/Sub di Konsol Developer (paling mudah), melalui alat command line (untuk penggunaan terprogram sederhana) atau menggunakan Cloud Pub/Sub API. Perhatikan bahwa Cloud Pub/Sub hanya mengizinkan topik dalam jumlah terbatas. Jadi, menggunakan satu topik untuk menerima semua notifikasi memastikan Anda tidak mengalami masalah penskalaan jika aplikasi Anda sudah populer.
Buat Langganan di Cloud Pub/Sub, untuk memberi tahu Cloud Pub/Sub cara mengirimkan notifikasi Anda.
Terakhir, sebelum mendaftar ke Notifikasi Push, Anda harus memberikan izin akun layanan Notifikasi Push (classroom-notifications@system.gserviceaccount.com) untuk memublikasikan topik Anda.

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

Mendaftarkan aplikasi Anda untuk mendapatkan 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/Sub yang diberikan dapat dijangkau oleh akun layanan notifikasi push. Metode ini gagal jika akun layanan notifikasi push tidak dapat menjangkau topik; misalnya, jika topik tidak ada atau Anda belum memberikan izin publikasi pada topik tersebut.

Otorisasi

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

Untuk feed perubahan daftar nama, ini berarti cakupan Daftar nama atau (idealnya) varian hanya bacanya (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 tugas kursus atau (idealnya) varian hanya bacanya (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 OAuth dari pengguna yang diberi otorisasi dengan cakupan yang diperlukan. Jika pengguna memutuskan koneksi aplikasi, notifikasi akan berhenti. Perhatikan bahwa saat ini, delegasi otorisasi tingkat domain tidak didukung untuk tujuan ini. Jika Anda mencoba mendaftar untuk pemberitahuan hanya menggunakan otorisasi 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, ini adalah courses.students atau courses.teachers. Untuk perubahan tugas kursus, nilainya adalah courses.courseWork atau courses.courseWork.studentSubmissions.
ID untuk resource yang berubah, dalam peta. Peta ini dirancang untuk mencocokkan argumen dengan metode get dari 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 course.courseWork akan memiliki kolom courseId dan id yang dapat dikirim tanpa diubah ke courses.courseWork.get() dan perubahan pada kolom courses.courseWork.get() akan dikirim courseIdidcourseWorkIdcourses.courseWork.studentSubmissions.get()

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 untuk pendaftaran yang menyebabkan notifikasi, yang dapat digunakan dengan registrations.delete() untuk membatalkan pendaftaran dari notifikasi.