Konfigurasi project Google Cloud

Halaman ini berisi informasi yang perlu Anda ketahui tentang cara membuat dan mengonfigurasi project Google Cloud untuk add-on Classroom. Project Google Cloud digunakan untuk menerapkan Single Sign-On Google melalui OAuth 2.0 (SSO Google), untuk mengizinkan permintaan yang dibuat oleh add-on Anda, dan untuk mengelola listingan add-on di toko Google Workspace Marketplace.

Untuk informasi umum selengkapnya tentang cara memublikasikan add-on ke Marketplace, lihat Memublikasikan aplikasi.

Pembuatan project Google Cloud

Ada dua jenis project yang dapat dibuat: project pribadi yang digunakan untuk pengembangan dan project publik yang dapat dijangkau oleh pengguna akhir. Label "publik" dan "pribadi" mengacu pada visibilitas aplikasi di Google Workspace Marketplace; aplikasi Marketplace pribadi hanya dapat diinstal oleh pengguna dalam domain tempat aplikasi dibuat, sedangkan aplikasi Marketplace publik tersedia untuk semua domain Google Workspace. Keduanya harus merupakan dua aplikasi yang terpisah, karena project tidak bisa bersifat publik dan pribadi. Aplikasi publik harus ditinjau dan disetujui sebelum tersedia di marketplace.

Untuk mengetahui informasi pembuatan project Google Cloud umum, buka Membuat project Google Cloud.

Membuat project Google Cloud pribadi

Project pribadi ini mewakili aplikasi add-on yang digunakan untuk pengembangan. URL ini tidak dapat diakses oleh pengguna di luar domain tempatnya dibuat, tetapi tidak perlu disetujui sebelum penginstalan. Oleh karena itu, Google merekomendasikan penggunaan project ini untuk mengembangkan dan menguji add-on Anda di lingkungan yang terkendali.

Anda memerlukan akses ke domain Google Workspace for Education dengan lisensi Teaching & Learning atau Plus untuk membuat project pribadi. Jika Anda belum memiliki akses ke domain tersebut, ikuti langkah-langkah berikut untuk menyiapkan domain demo Google Workspace for Education, mengupgradenya ke lisensi Plus, dan mengizinkannya mengakses API add-on Classroom:

  1. Selesaikan langkah-langkah untuk mendapatkan domain pengujian developer.

  2. Saat login sebagai administrator di domain demo, buat project Google Cloud baru.

  3. Aktifkan Classroom API.

  4. Aktifkan Google Workspace Marketplace SDK.

  5. Tetapkan Konfigurasi Aplikasi Visibilitas Aplikasi Marketplace SDK ke pribadi.

  6. Isi dan kirim formulir permintaan upgrade domain demo. Mengirimkan formulir ini akan meminta Google mengupgrade domain demo Anda ke Google Workspace for Education Plus dengan sepuluh lisensi dan memungkinkan project Cloud Anda masuk ke add-on API Classroom.

Membuat project Google Cloud publik

Project ini merepresentasikan aplikasi add-on yang dapat diakses oleh administrator, pengajar, dan siswa.

  1. Buat project Google Cloud baru dan aktifkan Google Workspace Marketplace SDK. Tetapkan Konfigurasi Aplikasi Visibilitas Aplikasi Marketplace SDK ke publik dan tidak publik. Anda tidak dapat membagikan atau mengonversi project pribadi yang digunakan selama pengujian internal. Project tersebut harus berupa nomor project baru.
  2. Bagikan ID project Google Cloud kepada partner Google Anda untuk menambahkan project ke daftar add-on yang diizinkan. Tindakan ini akan memberi project akses ke fitur add-on baru dari Classroom API.
  3. Setelah add-on Anda disetujui, tim Google Workspace Marketplace akan mengubah add-on dari "tidak publik" menjadi "tercantum" sehingga pengajar dapat menemukannya di toko.

OAuth 2.0

Akses ke Classroom API memerlukan izin akses data pengguna. Hal ini diperoleh dengan meminta akses Google ke cakupan OAuth untuk pengguna yang login dan menerima token yang dapat digunakan untuk selanjutnya melakukan panggilan API ke Google Classroom. Cakupan harus dikonfigurasi di listingan Play Store Google Workspace Marketplace agar administrator domain dapat memberikan izin atas nama pengguna domain jika mereka menginstal add-on.

Lihat halaman Cakupan OAuth untuk Google API untuk mengetahui daftar mendetail dari semua cakupan yang tersedia dan penggunaannya. Lihat halaman Mengonfigurasi OAuth dalam dokumentasi Workspace untuk mengetahui informasi konfigurasi OAuth umum.

Izin pengguna

Aplikasi web Anda harus meminta setidaknya salah satu cakupan berikut:

  • https://www.googleapis.com/auth/userinfo.email, yang memungkinkan aplikasi melihat alamat email pengguna.
  • https://www.googleapis.com/auth/userinfo.profile, yang memungkinkan aplikasi melihat informasi pribadi seperti potret, nama depan dan belakang, serta informasi pribadi lainnya yang telah tersedia untuk publik.

Setelah pengguna memberi otorisasi pada salah satu cakupan ini di add-on, cakupan tersebut diidentifikasi oleh parameter kueri login_hint. Parameter ini diteruskan ke salah satu URL aplikasi web Anda saat iframe dibuka. Jika pengguna belum memberikan otorisasi pada salah satu cakupan ini, parameter hd ("domain yang dihosting") akan diteruskan ke URL aplikasi web Anda.

login_hint dan hd adalah parameter OpenID Connect standar yang dapat Anda teruskan secara opsional ke Google saat menggunakan Login dengan Google atau meminta token OAuth. Hal ini dimaksudkan untuk membuat pengalaman otorisasi lebih lancar bagi pengguna akhir.

Cakupan add-on Classroom

Cakupan berikut bersifat khusus untuk add-on Classroom:

  • https://www.googleapis.com/auth/classroom.addons.teacher, yang memungkinkan akses ke semua metode API.
  • https://www.googleapis.com/auth/classroom.addons.student, yang memungkinkan akses untuk meluncurkan validasi dan operasi baca lampiran.

Meskipun jika token akses OAuth valid yang menunjukkan kredensial pengguna, panggilan API dilindungi oleh persyaratan tambahan:

  • Semua metode mengharuskan pengguna menjadi pengajar atau siswa dalam kursus yang ditentukan oleh courseId dalam permintaan.
  • Pembuatan, pembaruan, penghapusan, dan passback nilai lampiran mengharuskan pengguna menjadi pengajar.
  • Panggilan ke postingan Google Classroom tertentu dibatasi oleh pemeriksaan berikut.
    • Jika sudah memiliki setidaknya satu lampiran pada postingan, add-on dapat membuat permintaan untuk:
      • Validasi peluncuran iframe
      • Operasi pembacaan, pembaruan, dan penghapusan lampiran
      • Menilai pembaruan pada postingan tersebut
    • Saat iframe Penemuan Lampiran pertama kali dibuka, add-on mungkin belum memiliki lampiran di postingan. Disediakan parameter kueri addOnToken yang dapat digunakan untuk membuat permintaan untuk hal berikut:
      • Membuat lampiran di bawah postingan (addOnToken wajib diisi)
      • Validasi peluncuran (addOnToken divalidasi jika disediakan dan diperlukan saat add-on tidak memiliki lampiran pada postingan)

Verifikasi OAuth

Add-on Classroom menggunakan Google API untuk mengakses data pengguna Google.

Lihat FAQ verifikasi OAuth API untuk mengetahui informasi selengkapnya tentang proses verifikasi.

Listingan Google Workspace Marketplace

Ada beberapa hal yang perlu diperhatikan saat membuat listingan Play Store Marketplace untuk add-on Classroom saat menggunakan program akses awal ini.

Untuk informasi konfigurasi Google Workspace Marketplace SDK umum, buka Mengaktifkan dan mengonfigurasi Google Workspace Marketplace SDK dan Membuat listingan Play Store Google Workspace Marketplace.

Pertimbangan listingan

Listingan Play Store SDK Marketplace project Google Cloud publik Anda menentukan nama dan deskripsi aplikasi Anda yang ditujukan untuk pengguna akhir. Anda dapat memberikan detail ini dalam beberapa bahasa di bagian Detail Aplikasi.

Ikuti panduan berikut di listingan Anda:

  • Di bagian Detail Aplikasi:

    • Hindari tanda baca dalam Nama Aplikasi. Misalnya, gunakan "Add-on Saya oleh Perusahaan Saya" bukan "Perusahaan Saya: Add-on Saya" atau "Add-on Saya, dari Perusahaan Saya".

    • Deskripsi Singkat dan Deskripsi Mendetail tidak boleh berisi teks yang sama persis.

    • Pastikan Anda telah memilih nilai untuk kolom Harga. Kolom ini mencakup opsi Gratis, Berbayar dengan uji coba gratis, Berbayar dengan fitur gratis, dan harga Berbayar. Anda tidak perlu menentukan jumlah biaya di listingan Marketplace.

    • Pastikan Anda telah memilih nilai untuk kolom Kategori. Referensi Akademis atau Alat Pengajar dan Admin mungkin merupakan pilihan yang baik untuk add-on Classroom.

    • Lihat item yang tercantum dalam Deskripsi detail aplikasi Marketplace untuk informasi selengkapnya.

  • Di bagian Aset Grafik:

  • Pada Link Dukungan:

    • Pastikan Anda telah memberikan link ke Persyaratan Layanan aplikasi Anda.

  • Pastikan Anda memenuhi Panduan Branding Google API, yang mencakup nama dan deskripsi yang diizinkan.

  • Jika Anda merujuk ke produk Google apa pun dalam listingan, gunakan namanya dalam format yang disediakan di Daftar Merek Dagang. Pastikan Anda menyertakan simbol merek dagang (TM) jika dicantumkan; gunakan "Google DokumenTM", bukan "Google Dokumen".

Integrasikan dengan layanan pemberian lisensi dan penagihan Google

Jika Anda berminat untuk mengizinkan aplikasi Google Workspace Marketplace Anda berintegrasi dengan layanan pemberian lisensi dan penagihan Google, kunjungi Marketplace API.

Setelan penginstalan

Add-on dapat mengizinkan penginstalan individual selain penginstalan administrator. Halaman ini menyoroti beberapa perbedaan antara kedua jenis penginstalan tersebut. Halaman ini tidak dimaksudkan untuk mempromosikan kedua jenis penginstalan tersebut. Anda dapat memilih apakah akan mengizinkan penginstalan individual di halaman Konfigurasi Aplikasi Google Workspace Marketplace SDK.

Penginstalan administrator

Penginstalan administrator memungkinkan administrator menambahkan add-on ke semua akun dalam domain atau ke grup akses atau unit organisasi tertentu. Hanya administrator domain yang dapat melakukan penginstalan administrator. Secara opsional, administrator dapat mengizinkan semua cakupan akses atas nama semua pengguna di domain; pengguna tidak akan diminta untuk mengizinkan cakupan akses mana pun jika administrator memilih untuk melakukannya.

Berikut adalah beberapa pertimbangan terkait penginstalan administrator.

  • Kontrol lebih ketat. Administrator dapat membatasi pengguna yang dapat mengakses add-on.
  • Kompatibilitas dengan pemberian lisensi. Jika aplikasi Anda memerlukan lisensi, menyalurkan penginstalan melalui administrator dapat membantu memastikan bahwa lisensi didistribusikan dan digunakan dengan tepat dengan institusi yang sesuai.
  • Mengurangi beban pada pengguna akhir. Instalasi administrator mengurangi beban penyiapan untuk pengajar dan siswa. Hal ini dapat menghasilkan pengalaman pengguna yang lebih lancar dengan lebih sedikit klik dan lebih sedikit peluang kebingungan.

Lihat Menginstal aplikasi Marketplace di domain Anda untuk mengetahui informasi selengkapnya tentang cara melakukan penginstalan administrator dan Cara kerja struktur organisasi untuk mempelajari lebih lanjut unit organisasi dan grup akses.

Penginstalan individual

Penginstalan individual akan menambahkan add-on ke akun pengguna. Pengguna diminta untuk mengizinkan cakupan akses add-on selama penginstalan.

Berikut adalah beberapa pertimbangan terkait penginstalan individual.

  • Memfasilitasi adopsi. Lebih banyak pengguna dapat melihat dan menginstal add-on Anda dari Google Workspace Marketplace. Mengizinkan penginstalan individual dapat meminta lebih banyak pengajar mengadopsi atau mendukung produk Anda.
  • Pengujian administrator. Administrator dapat menginstal add-on satu per satu untuk menguji atau mengevaluasinya sebelum menyetujui atau menginstalnya untuk grup yang lebih luas.

Selain menginstal add-on atas nama pengguna, administrator juga dapat mempertahankan daftar yang diizinkan untuk mengizinkan pengguna menginstal add-on yang memungkinkan penginstalan individual. Jika add-on tidak tercantum dalam daftar yang diizinkan, pengguna masih dapat melihat listingan add-on di Google Workspace Marketplace, tetapi tidak dapat menginstal add-on tersebut. Sebagai gantinya, pengguna akan melihat pesan yang menjelaskan bahwa add-on tersebut belum diizinkan untuk diinstal oleh administrator domain. Lihat Mengelola aplikasi Google Workspace Marketplace dalam daftar yang diizinkan untuk mempelajari perilaku ini lebih lanjut.

Lihat dokumentasi setelan penginstalan Google Workspace Marketplace untuk mengetahui informasi selengkapnya.

Integrasi Apl

Anda harus memberikan URL iframe peluncuran di kolom URI Penyiapan Lampiran. URL ini digunakan sebagai nilai src iframe untuk iframe Discovery Lampiran. iframe Penemuan Lampiran digunakan oleh pengajar untuk menemukan konten atau aktivitas untuk dilampirkan ke tugasnya.

Anda juga harus menentukan semua awalan URI tempat lampiran diizinkan dari add-on Anda. Fitur ini meningkatkan keamanan dengan mencegah lampiran dari sumber tidak sah.

Lihat halaman panduan iframe untuk detail selengkapnya terkait kolom ini.

Akun pengujian

Buat akun pengujian di domain demo untuk memverifikasi perilaku add-on pribadi yang benar. Diperlukan dua akun siswa untuk menguji peralihan antar-siswa di iframe Tinjauan Tugas Siswa.

Akun pengujian yang disarankan:

  • Tammy Pengajar, tammy.teacher@<domain demo Anda>
  • Siswa Sam, sam.student@<domain demo Anda>
  • Siswa Sally, sally.student@<domain demo Anda>

Ikuti prosedur ini untuk membuat akun pengujian baru:

  1. Login ke konsol Admin.
  2. Buka Pengguna.
  3. Klik Add new user (lihat Gambar 1).
  4. Masukkan informasi pengguna dan tetapkan peran yang sesuai.

Klik Tambahkan pengguna baru Gambar 1. Lokasi link Tambahkan pengguna baru dalam konsol Admin.

Ikuti prosedur berikut untuk membuat grup pengujian baru:

  1. Login ke konsol Admin.
  2. Buka Grup.
  3. Klik Buat grup (lihat Gambar 2).
  4. Masukkan anggota dan pemilik grup.

Klik Buat grup Gambar 2. Lokasi link Buat grup dalam konsol Admin.