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 dalam 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 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 nama siswa untuk kursus 1234".
Pendaftaran adalah petunjuk bagi Classroom API untuk mengirimkan notifikasi dari feed tertentu ke tujuan.

Setelah Anda membuat pendaftaran untuk feed, topik Cloud Pub/Sub pendaftaran tersebut menerima notifikasi dari feed tersebut hingga masa berlakunya habis. Pendaftaran Anda berlangsung selama seminggu, tetapi Anda dapat memperpanjangnya kapan saja sebelum masa berlakunya habis 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 akan ditayangkan 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 dalam kursus tersebut.
Setiap kursus memiliki feed perubahan tugas kursus untuk kursus, yang menampilkan notifikasi saat tugas kursus 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 web hook, 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 Konsol Developer Anda.
Buat topik Cloud Pub/Sub di Konsol Developer (paling mudah), melalui alat command line (untuk penggunaan terprogram yang 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.
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 kepada akun layanan Notifikasi Push (classroom-notifications@system.gserviceaccount.com) untuk memublikasikan ke topik Anda.

CATATAN: Jika Anda memberikan izin kepada akun layanan Notifikasi Push untuk memublikasikan topik Cloud Pub/Sub, pengguna yang dapat membuat permintaan dari project Konsol Developer Anda akan dapat menentukan bahwa project tersebut ada, dan mendaftar untuk menerima notifikasi. Banyak aplikasi yang menyimpan Client ID OAuth di sisi klien, sehingga pengguna akhir mungkin dapat membuat permintaan dari project Konsol Developer Anda. Jika ini berlaku untuk Anda, dan Anda khawatir pengguna akhir yang 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 notifikasi push dari project Konsol Developer yang berbeda.

Mendaftarkan aplikasi untuk 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 disediakan dapat dijangkau oleh akun layanan notifikasi push. Metode akan gagal jika akun layanan notifikasi push tidak dapat menjangkau topik; misalnya, jika topik tidak ada atau Anda belum memberinya izin publikasi tentang 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 dikirim.

Untuk feed perubahan daftar nama siswa, ini berarti cakupan Daftar Nama Siswa 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, hal ini berarti versi "siswa" dari cakupan tugas 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 dikirimkan, aplikasi harus mempertahankan pemberian OAuth dari pengguna yang diotorisasi dengan cakupan yang diperlukan. Jika pengguna memutuskan sambungan aplikasi, notifikasi akan berhenti. Perhatikan bahwa saat ini, pendelegasian otoritas tingkat domain tidak didukung untuk tujuan ini. Jika Anda mencoba mendaftar untuk notifikasi menggunakan otoritas yang didelegasikan di seluruh domain saja, Anda akan menerima error @MissingGrant.

Menerima notifikasi

Notifikasi dienkode dengan JSON, dan berisi:

Nama koleksi berisi resource yang berubah. Untuk notifikasi tentang perubahan daftar nama siswa, statusnya dapat berupa courses.students atau courses.teachers. Untuk perubahan tugas kursus, parameternya adalah courses.courseWork atau courses.courseWork.studentSubmissions.
ID untuk resource yang berubah, di peta. Peta ini didesain 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 course.courseWork akan memiliki kolom courseId dan id yang dapat dikirim tanpa diubah ke courses.courseWork.get() dan perubahan pada kolom courses.courseWork() yang akan dikirim dan idsudahdiubahyang akan dikirim ke idcourse.courseWork.get() dan tidak akan diubah.courseIdcourseWorkIdcourses.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.