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 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 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 peserta 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 berakhir. Pendaftaran Anda berlangsung selama seminggu, tetapi Anda dapat memperpanjangnya kapan saja sebelum masa berlakunya berakhir dengan membuat permintaan yang 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 tidak akan lagi dikirim.

Jenis feed

Classroom API menawarkan tiga jenis feed:

Setiap domain memiliki feed perubahan daftar nama 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 tersebut.
Setiap kursus memiliki feed perubahan tugas kursus untuk kursus, yang menampilkan notifikasi saat ada objek tugas kursus atau kiriman siswa yang 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 webhook, atau dengan melakukan polling pada endpoint langganan.

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

Pastikan Anda memenuhi Prasyarat Cloud Pub/Sub.
Siapkan klien Cloud Pub/Sub.
Tinjau harga Cloud Pub/Sub, dan aktifkan penagihan untuk project Konsol Developer 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 sejumlah topik, jadi menggunakan satu topik untuk menerima semua notifikasi memastikan Anda tidak mengalami masalah penskalaan jika aplikasi Anda menjadi populer.
Buat Langganan di Cloud Pub/Sub, untuk memberi tahu Cloud Pub/Sub cara mengirimkan notifikasi Anda.
Terakhir, sebelum mendaftar untuk Notifikasi Push, Anda harus memberikan izinke akun layanan Notifikasi Push (classroom-notifications@system.gserviceaccount.com) untuk memublikasikan ke topik Anda.

Mendaftarkan aplikasi Anda untuk menerima notifikasi

Setelah memiliki topik yang dapat dipublikasikan oleh akun layanan notifikasi push Classroom API, Anda dapat mendaftar untuk menerima 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 akan gagal jika akun layanan push notification 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 mendapatkan otorisasi 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, hal 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, hal ini berarti versi "siswa" dari cakupan tugas 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 berwenang dengan cakupan yang diperlukan. Jika pengguna memutuskan koneksi aplikasi, notifikasi akan berhenti. Perhatikan bahwa saat ini, delegasi otoritas tingkat domain tidak didukung untuk tujuan ini. Jika Anda mencoba mendaftar untuk notifikasi hanya menggunakan otorisasi yang didelegasikan di seluruh domain, Anda akan menerima error @MissingGrant.

Terima notifikasi

Notifikasi dienkode dengan JSON, dan berisi:

Nama koleksi yang berisi resource yang berubah. Untuk notifikasi tentang perubahan jadwal, nilai ini adalah courses.students atau courses.teachers. Untuk perubahan tugas kursus, nilai ini 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 siswa, kolom courseId dan userId akan diisi, dan dapat dikirim tanpa diubah ke courses.students.get() atau courses.teachers.get(). Demikian pula, perubahan pada kumpulan data courses.courseWork akan memiliki kolom courseId dan id yang dapat dikirim tanpa diubah ke courses.courseWork.get() dan perubahan pada kumpulan data courses.courseWork.studentSubmissions akan memiliki kolom courseId, courseWorkId, dan id yang dapat dikirim tanpa diubah ke courses.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.