Pengajar yang memanfaatkan Classroom dan alat pihak ketiga menghadapi tantangan untuk menyiapkan kursus dan daftar nama siswa di berbagai platform. Hal ini dapat dilakukan secara manual, baik melalui upload CSV maupun memasukkan email satu per satu. Namun, dengan Classroom API, alat pihak ketiga dapat mengurangi beban kerja pengajar melalui integrasi dengan kasus penggunaan API yang paling umum: impor daftar nama siswa.
Pengimporan daftar nama siswa memungkinkan platform pihak ketiga mengambil metadata, pengajar, dan siswa kursus berdasarkan kursus dengan izin pengajar atau admin. Pengajar dapat mengambil detail kursus yang mereka ajar, sedangkan admin memiliki akses ke detail untuk semua kursus di seluruh domain. Fleksibilitas ini memungkinkan developer melakukan aktivasi daftar nama siswa Classroom ke platform mereka dengan lancar, baik pada tingkat pengajar maupun di seluruh domain menggunakan kredensial admin.
Sebelum mendalami detail teknis tentang seperti apa integrasi impor daftar nama siswa, mari kita tinjau contoh alur kerja terlebih dahulu:
Di aplikasi pihak ketiga, pengajar memilih opsi untuk mengimpor Kursus Classroom.
Aplikasi pihak ketiga memanggil metode
courses.listmelalui Classroom API, yang akan menampilkan JSON respons dengan semua kursus pengajar.Dari respons JSON, aplikasi pihak ketiga akan menampilkan judul kursus pengajar agar dapat dipilih oleh pengajar. Pendaftaran harus melacak ID kursus untuk melanjutkan ke langkah berikutnya.
Dengan ID kursus yang dipilih, aplikasi pihak ketiga memanggil metode
students.listdanteachers.listserta menampilkan semua nama di situsnya untuk dikonfirmasi oleh pengajar untuk diimpor.Menggunakan email yang ditampilkan di JSON respons
students.listdanteachers.list, aplikasi pihak ketiga akan mengundang pengguna untuk bergabung ke kursus yang baru diimpor di platform mereka.
Untuk setiap metode yang disebutkan dalam alur kerja, Anda dapat menggunakan API Explorer untuk melihat secara persis perilaku setiap metode. Kami juga merekomendasikan pra-bacaan berikut sebelum menyelesaikan panduan ini:
Memulai
Sebelum mengimplementasikan detail impor daftar nama siswa Classroom, Anda harus menentukan kursus dan informasi pengguna yang perlu diambil melalui API. Anda dapat melihat metadata Kursus yang tersedia di Dokumentasi referensi, tetapi beberapa kolom wajib atau umum yang diperlukan dapat dirangkum di bawah:
| Kolom | Gunakan |
|---|---|
| id | Diperlukan untuk permintaan API yang mengambil siswa atau pengajar |
| name | Direkomendasikan untuk kemudahan penggunaan bagi pengguna, yaitu menampilkan di situs Anda |
| ownerId | Wajib saat mengimpor di seluruh domain untuk mengidentifikasi pengajar utama kursus dengan benar |
Informasi kursus ini diambil pada langkah courses.list dalam alur kerja
di atas. Dalam permintaan ini, Anda dapat menentukan parameter permintaan tertentu. Meskipun tidak ada yang diperlukan untuk metode ini, beberapa parameter yang direkomendasikan adalah:
| Parameter | Gunakan |
|---|---|
| courseState | Jika tidak ditentukan, API akan menampilkan kursus dari keenam status kursus. Sebaiknya tetapkan ACTIVE untuk mengambil kursus yang saat ini digunakan pengajar. |
| pageSize | Bagi pengajar yang mengimpor kursus mereka sendiri, sebaiknya tentukan pageSize yang kecil (kurang dari 10) untuk mengurangi waktu respons panggilan API. |
| pageToken | Wajib ada jika Anda menggunakan permintaan halaman. |
| teacherId | Direkomendasikan karena admin domain sering mengajar kursus. Jika tidak ditentukan, permintaan akan menampilkan kursus untuk pengajar di seluruh domain. |
| fields | Sebaiknya kurangi waktu respons panggilan API. |
Dengan menggunakan ID kursus yang diambil sebelumnya, aplikasi Anda kini dapat mengambil
daftar siswa dan rekan pengajar untuk kursus atau kursus tersebut. ID kursus ini adalah
satu-satunya parameter kueri yang diperlukan untuk teachers.list dan students.list, tetapi
Anda juga dapat mempertimbangkan untuk menentukan parameter pageSize dan fields
guna mengurangi waktu respons panggilan API Anda.
Semua kolom yang tersedia untuk referensi
siswa
dan pengajar
dapat ditemukan di dokumentasi masing-masing. Dua kolom yang paling
umum digunakan dan biasanya wajib diisi adalah kolom profile:
profile.name dan profile.emailAddress.
| Kolom | Gunakan |
|---|---|
| profile.name | Direkomendasikan untuk kemudahan penggunaan bagi pengguna, yaitu menampilkan di situs Anda |
| profile.emailAddress | Diperlukan untuk aplikasi yang ingin mengidentifikasi siswa secara unik |
Untuk mengambil dan menggunakan detail kursus atau daftar nama siswa ini dari Classroom, aplikasi Anda harus meminta otorisasi dari pengguna. Ada tiga (3) cakupan yang diperlukan untuk mengimplementasikan alur kerja ini:
- https://www.googleapis.com/auth/classroom.courses.readonly
- Memberikan akses Hanya Baca ke Kursus Google Classroom
- https://www.googleapis.com/auth/classroom.rosters.readonly
- Memberikan akses Hanya Baca ke daftar nama Kursus Google Classroom (pengajar dan siswa)
- https://www.googleapis.com/auth/classroom.profile.emails
- Memberikan akses Baca ke properti email milik pengajar dan siswa
Menyinkronkan Daftar Nama Siswa dengan Notifikasi Pub/Sub
Seiring berjalannya tahun ajaran, daftar nama siswa dapat berubah saat siswa berhenti atau menambahkan mata pelajaran. Menambahkan notifikasi Pub/Sub akan memungkinkan Anda untuk membuat aplikasi pihak ketiga tetap sinkron dengan daftar nama Classroom. Untuk menerima notifikasi, siapkan topik Google Cloud Pub/Sub, lalu daftarkan topik dengan API Classroom. Pendaftaran ini adalah permintaan agar Classroom mengirim data dari feed yang diberikan ke topik yang ditentukan. Feed ini akan menjadi pemicu acara untuk menyinkronkan ulang dengan daftar nama siswa Classroom pengajar.
Menggunakan notifikasi push akan memerlukan satu cakupan tambahan, yang tidak harus dikirimkan untuk verifikasi:
- https://www.googleapis.com/auth/classroom.push-notifications
- Mengizinkan aplikasi Anda mendaftar ke aktivitas notifikasi push apa pun
Untuk mengetahui detail selengkapnya tentang cara berintegrasi dengan notifikasi push Classroom, lihat panduan Mengelola Notifikasi Push kami.