Pengantar

Pengajar yang memanfaatkan Classroom dan alat pihak ketiga menghadapi tantangan dalam menyiapkan kursus dan daftar nama siswa di beberapa platform. Tindakan ini dapat dilakukan secara manual, baik melalui penggunaan upload CSV atau memasukkan email satu per satu. Namun, dengan Classroom API, alat pihak ketiga dapat mengurangi beban kerja pengajar dengan berintegrasi dengan kasus penggunaan API yang paling umum: impor daftar siswa.

Impor daftar nama siswa memungkinkan platform pihak ketiga mengambil metadata kursus, pengajar, dan siswa berdasarkan kursus dengan izin pengajar atau admin. Pengajar dapat mengambil detail kursus yang mereka ajarkan, sedangkan admin memiliki akses ke detail untuk semua kursus di seluruh domain. Fleksibilitas ini memungkinkan developer mengintegrasikan daftar kelas ke platform mereka secara lancar, baik di tingkat pengajar perorangan maupun di seluruh domain dengan menggunakan kredensial admin.

Admin domain dapat menggunakan alat pihak ketiga sebagai pengajar di kursus mereka sendiri. Penanganan yang cermat terhadap perbedaan antara izin admin domain dan pengajar diperlukan saat mengambil detail kursus melalui API.

Sebelum mempelajari detail teknis seperti apa integrasi impor daftar nama mungkin terlihat, mari kita tinjau terlebih dahulu contoh alur kerja:

1. Di aplikasi pihak ketiga, pengajar memilih opsi untuk mengimpor Kursus Classroom.

2. Aplikasi pihak ketiga memanggil metode courses.list melalui Classroom API, yang akan menampilkan JSON respons dengan semua kursus pengajar.

3. Dari respons JSON, aplikasi pihak ketiga menampilkan judul kursus pengajar agar pengajar dapat memilih salah satunya. Aplikasi harus melacak ID kursus untuk melanjutkan ke langkah berikutnya.

4. Dengan ID kursus yang dipilih, aplikasi pihak ketiga memanggil metode students.list dan teachers.list serta menampilkan semua nama di situsnya agar dikonfirmasi oleh pengajar untuk diimpor.

5. Dengan menggunakan email yang ditampilkan dalam json respons students.list dan teachers.list, aplikasi pihak ketiga mengundang pengguna untuk bergabung dengan kursus yang baru diimpor di platform mereka.

Untuk setiap metode yang disebutkan dalam alur kerja, Anda dapat menggunakan API Explorer untuk melihat secara persis cara kerja setiap metode. Sebaiknya baca juga artikel berikut sebelum menyelesaikan panduan ini:

1. Mengelola Kursus dengan Classroom API
2. Mengelola Siswa dan Pengajar

Selain diagram alur kerja di bawah, lihat contoh aktif ActivelyLearn untuk lebih memahami jenis integrasi ini.

Memulai

Sebelum menerapkan spesifikasi impor daftar kelas, Anda harus menentukan informasi kursus dan 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 diringkas di bawah:

Kolom	Gunakan
id	Diperlukan untuk permintaan API yang mengambil siswa atau pengajar
nama	Direkomendasikan untuk kemudahan penggunaan bagi pengguna, yaitu ditampilkan di situs Anda
ownerId	Wajib diisi saat mengimpor berdasarkan seluruh domain untuk mengidentifikasi pengajar utama kursus dengan benar

Informasi kursus ini diambil pada langkah courses.list alur kerja di atas. Dalam permintaan ini, Anda dapat menentukan parameter permintaan tertentu. Meskipun tidak ada parameter yang wajib untuk metode ini, beberapa parameter yang direkomendasikan adalah:

Parameter	Gunakan
courseState	Jika tidak ditentukan, API akan menampilkan kursus dari keenam status kursus. Sebaiknya tentukan ACTIVE untuk mengambil kursus yang saat ini digunakan pengajar.
pageSize	Untuk pengajar yang mengimpor kursus mereka sendiri, sebaiknya tentukan pageSize kecil (kurang dari 10) untuk mengurangi waktu respons panggilan API.
pageToken	Diperlukan jika Anda menggunakan permintaan berhalaman.
teacherId	Direkomendasikan karena admin domain sering kali mengajar kursus. Jika tidak ditentukan, permintaan akan menampilkan kursus untuk pengajar di seluruh domain.
Fields	Direkomendasikan untuk mengurangi waktu respons panggilan API.

Dengan menggunakan ID kursus yang diambil sebelumnya, aplikasi Anda kini dapat mengambil daftar siswa dan rekan pengajar untuk kursus tersebut. ID kursus ini adalah satu-satunya parameter kueri yang diperlukan untuk teachers.list dan students.list, tetapi Anda mungkin juga ingin mempertimbangkan untuk menentukan parameter pageSize dan fields untuk mengurangi waktu respons panggilan API Anda.

Semua kolom yang tersedia untuk resource siswa dan pengajar dapat ditemukan dalam dokumentasinya masing-masing. Dua kolom yang paling umum digunakan dan biasanya diperlukan berada di kolom profile: profile.name dan profile.emailAddress.

Kolom	Gunakan
profile.name	Direkomendasikan untuk kemudahan penggunaan bagi pengguna, yaitu ditampilkan di situs Anda
profile.emailAddress	Diperlukan untuk aplikasi yang ingin mengidentifikasi siswa secara unik

Untuk mengambil dan menggunakan detail kursus atau daftar siswa dari Classroom, aplikasi Anda harus meminta otorisasi dari pengguna. Ada tiga (3) cakupan yang diperlukan untuk menerapkan 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 siswa Kursus Google Classroom (pengajar dan siswa)
• https://www.googleapis.com/auth/classroom.profile.emails
  • Memberikan akses Baca ke properti email pengajar dan siswa

Karena salah satu cakupan ini dianggap sensitif, aplikasi Anda harus menyelesaikan proses verifikasi.

Menyinkronkan Daftar Nama dengan Notifikasi Pub/Sub

Seiring berjalannya tahun ajaran, daftar nama siswa dapat berubah saat siswa keluar atau menambahkan mata pelajaran. Menambahkan notifikasi Pub/Sub akan memungkinkan Anda menyinkronkan aplikasi pihak ketiga dengan daftar nama Classroom. Untuk menerima notifikasi, Anda menyiapkan topik Google Cloud Pub/Sub, lalu mendaftarkan topik tersebut dengan Classroom API. Pendaftaran ini adalah permintaan agar Classroom mengirim data dari feed yang diberikan ke topik yang diberikan. Feed ini akan menjadi pemicu acara untuk menyinkronkan ulang dengan daftar nama kelas pengajar.

Bergantung pada kasus penggunaan aplikasi, Anda dapat berlangganan notifikasi berdasarkan per kursus atau per domain.

Penggunaan notifikasi push akan memerlukan satu cakupan tambahan, yang tidak perlu dikirimkan untuk verifikasi:

• https://www.googleapis.com/auth/classroom.push-notifications
  • Mengizinkan aplikasi Anda mendaftar untuk aktivitas notifikasi push apa pun

Untuk mengetahui detail selengkapnya tentang cara berintegrasi dengan notifikasi push Classroom, lihat panduan Mengelola Notifikasi Push kami.