Rangkaian panduan ini menggambarkan semua bagian penting dari add-on Classroom yang berfungsi. Setiap langkah panduan akan membahas konsep tertentu, yang menerapkannya dalam satu aplikasi web. Tujuannya adalah untuk membantu Anda menyiapkan, mengonfigurasi, dan meluncurkan add-on yang fungsional.
Add-on Anda harus berinteraksi dengan project Google Cloud. Jika Anda belum terbiasa dengan Google Cloud, sebaiknya baca Panduan Memulai. Anda dapat mengelola kredensial, akses API, dan GWM SDK di Konsol Google Cloud. Untuk mengetahui informasi selengkapnya tentang GWM SDK, buka halaman panduan listingan Google Workspace Marketplace.
Panduan ini mencakup topik berikut:
- Gunakan Google Cloud untuk membuat halaman yang akan ditampilkan dalam iframe di Classroom.
- Menambahkan single sign-on (SSO) Google dan mengizinkan pengguna login.
- Lakukan panggilan API untuk melampirkan add-on Anda ke tugas.
- Penuhi persyaratan pengiriman add-on utama dan fitur yang diperlukan.
Panduan ini mengasumsikan bahwa Anda sudah memahami konsep pemrograman dan pengembangan web mendasar. Sebaiknya baca Panduan konfigurasi project sebelum memulai panduan. Halaman ini berisi detail konfigurasi penting yang tidak sepenuhnya dibahas dalam panduan.
Contoh penerapan
Contoh referensi lengkap tersedia di JavaScript, Python, dan Java. Implementasi ini adalah sumber kode contoh yang ditemukan di halaman berikutnya.
Tempat mendownload
Arsip lengkap contoh kami dapat didownload menggunakan link di bawah.
Prasyarat
Tinjau bagian berikut untuk menyiapkan project add-on baru.
Sertifikat HTTPS
Meskipun Anda dapat menghosting aplikasi di lingkungan pengembangan apa pun, add-on Classroom hanya tersedia melalui https://
. Oleh karena itu, Anda memerlukan server dengan enkripsi SSL untuk men-deploy aplikasi atau mengujinya dalam iframe add-on.
localhost
dapat digunakan dengan sertifikat SSL. Pertimbangkan mkcert jika Anda perlu membuat sertifikat untuk pengembangan lokal.
Project Google Cloud
Anda perlu mengonfigurasi project Google Cloud untuk digunakan dengan contoh ini. Lihat panduan Pembuatan project Google Cloud untuk mengetahui ringkasan langkah-langkah yang diperlukan untuk memulai. Bagian Menyiapkan project Google Cloud dalam panduan pertama juga membahas tindakan konfigurasi tertentu yang akan diambil.
Setelah selesai, download Client ID OAuth 2.0 Anda sebagai file JSON; Anda perlu menambahkan file kredensial ini ke direktori contoh yang telah diekstrak. Lihat Memahami file untuk lokasi tertentu.
Kredensial OAuth
Ikuti langkah-langkah berikut untuk membuat kredensial OAuth baru:
- Buka halaman Google Cloud Credentials. Pastikan Anda telah memilih project yang tepat di bagian atas layar.
- Klik BUAT KREDENSIAL dan pilih ID klien OAuth dari menu drop-down.
- Di halaman berikutnya:
- Setel Jenis aplikasi ke Aplikasi web.
- Di bagian URI pengalihan yang diotorisasi, klik TAMBAHKAN URI. Tambahkan jalur lengkap rute callback untuk aplikasi Anda. Misalnya,
https://my.domain.com/auth-callback
atauhttps://localhost:5000/callback
. Anda akan membuat dan menangani rute ini nanti dalam panduan ini. Anda dapat mengedit atau menambahkan rute lainnya kapan saja. - Klik BUAT.
- Anda kemudian akan menerima dialog berisi kredensial yang baru dibuat. Pilih opsi
DOWNLOAD JSON. Salin file
.json
yang didownload ke direktori server Anda.
Prasyarat khusus bahasa
Lihat file README di setiap arsip untuk mengetahui daftar prasyarat terbaru.
Python
Contoh Python kita menggunakan framework Flask. Anda dapat mengunduh kode sumber lengkap dari tautan di atas.
Jika perlu, instal Python 3.7+ dan pastikan
pip
tersedia.
python3 -m ensurepip --upgrade
Sebaiknya Anda juga menyiapkan dan mengaktifkan lingkungan virtual Python baru.
python3 -m venv .classroom-addon-env
source .classroom-addon-env/bin/activate
Terdapat requirements.txt
di setiap subdirektori panduan dalam
contoh yang didownload. Anda dapat dengan cepat menginstal library yang diperlukan menggunakan
pip
. Gunakan perintah berikut untuk menginstal library yang diperlukan untuk
panduan pertama.
cd flask/01-basic-app
pip install -r requirements.txt
Node.js
Contoh Node.js kami menggunakan framework Express. Anda dapat mengunduh kode sumber lengkap dari tautan di atas.
Contoh ini memerlukan Node.js v16.13 atau yang lebih baru.
Instal modul node yang diperlukan menggunakan npm
.
npm install
Java
Contoh Java kami menggunakan framework Spring Boot. Anda dapat mengunduh kode sumber lengkap dari tautan di atas.
Instal Java 11+ jika Anda belum menginstalnya di komputer.
Aplikasi Spring Boot dapat menggunakan Gradle atau Maven untuk menangani build dan mengelola dependensi. Contoh ini mencakup wrapper Maven yang memastikan build yang berhasil tanpa mengharuskan Anda menginstal Maven sendiri.
Di direktori tempat Anda telah mendownload atau meng-clone project, jalankan perintah berikut guna memastikan Anda memiliki prasyarat untuk menjalankan project.
java --version
./mvnw --version
Atau di Windows:
java -version
mvnw.cmd --version
Memahami file
Bagian berikut menjelaskan tata letak direktori contoh.
Nama direktori
Setiap arsip berisi beberapa direktori yang namanya diawali dengan angka, seperti
/01-basic-app/
. Angka-angka tersebut sesuai dengan langkah-langkah panduan tertentu. Setiap direktori berisi aplikasi web yang berfungsi penuh, yang mengimplementasikan fitur yang dijelaskan dalam panduan tertentu. Misalnya, direktori /01-basic-app/
berisi implementasi akhir untuk panduan
Membuat add-on.
Konten direktori
Konten direktori berbeda bergantung pada bahasa penerapan:
Python
Directory root berisi file berikut:
main.py
- titik entri aplikasi Python. Tentukan konfigurasi server yang ingin Anda gunakan di file ini, lalu jalankan untuk memulai server.requirements.txt
- modul Python yang diperlukan untuk menjalankan aplikasi web. Modul ini dapat diinstal secara otomatis menggunakanpip install -r requirements.txt
.client_secret.json
- file rahasia klien yang didownload dari Google Cloud. Perhatikan bahwa ini tidak disertakan dalam arsip contoh; Anda harus mengganti nama dan menyalin file kredensial yang didownload ke setiap root direktori.
config.py
- opsi konfigurasi untuk server Flask.Direktori
webapp
berisi konten untuk aplikasi web. Paket ini mencakup:Direktori
/templates/
dengan template Jinja untuk berbagai halaman.Direktori
/static/
dengan file gambar, CSS, dan JavaScript tambahan.routes.py
- metode pengendali untuk rute aplikasi web.__init__.py
- penginisialisasi untuk modulwebapp
. Inisialisasi ini memulai server Flask dan memuat opsi konfigurasi yang ditetapkan diconfig.py
.File tambahan yang diperlukan oleh langkah panduan tertentu.
Node.js
Setiap langkah dari walkthrough dapat ditemukan di subfolder <step>
-nya sendiri. Setiap langkah berisi:
- File statis seperti JavaScript, CSS, dan gambar ditemukan di folder
./<step>/public
. - Router Express ditemukan di folder
./<step>/routes
. - Template HTML ditemukan di folder
./<step>/views
. - Aplikasi server adalah
./<step>/app.js
.
Java
Direktori project meliputi hal-hal berikut:
- Direktori
src.main
berisi kode sumber dan konfigurasi agar aplikasi berhasil dijalankan. Direktori ini mencakup hal-hal berikut: +java.com.addons.spring
yang berisi fileApplication.java
danController.java
. FileApplication.java
bertanggung jawab untuk menjalankan server aplikasi sementara fileController.java
menangani logika endpoint. + direktoriresources
berisi direktoritemplates
dengan file HTML dan JavaScript. Objek ini juga berisi fileapplication.properties
yang menentukan port untuk menjalankan server, jalur ke file keystore, dan jalur ke direktoritemplates
. Contoh ini menyertakan file keystore dalam direktoriresources
. Anda dapat menyimpannya di mana saja, tetapi pastikan Anda mengupdate fileapplication.properties
dengan jalur yang sesuai.pom.xml
berisi informasi yang diperlukan untuk membangun project dan menentukan dependensi yang diperlukan..gitignore
berisi nama file yang tidak boleh diupload ke git. Pastikan Anda menambahkan jalur ke keystore di.gitignore
ini. Dalam contoh yang diberikan, atribut ini adalahsecrets/*.p12
(tujuan keystore dibahas di bagian di bawah). Untuk panduan 2 dan selanjutnya, Anda juga harus menyertakan jalur ke fileclient_secret.json
untuk memastikan bahwa Anda tidak menyertakan secret di repositori jarak jauh. Untuk panduan 3 dan seterusnya, Anda harus menambahkan jalur ke file database H2 dan factory datastore file. Informasi selengkapnya tentang penyiapan penyimpanan data ini dapat ditemukan dalam panduan ketiga tentang menangani kunjungan berulang.mvnw
danmvnw.cmd
masing-masing adalah wrapper Maven yang dapat dieksekusi untuk Unix dan Windows. Misalnya, menjalankan./mvnw --version
di Unix akan menghasilkan versi Apache Maven, di antara informasi lainnya.- Direktori
.mvn
berisi konfigurasi untuk wrapper Maven.
Menjalankan server contoh
Anda harus meluncurkan server agar dapat mengujinya. Ikuti petunjuk di bawah untuk menjalankan server contoh dalam bahasa pilihan Anda:
Python
Kredensial OAuth
Buat dan download kredensial OAuth Anda seperti yang dijelaskan di atas. Tempatkan file .json
di direktori utama bersama dengan file peluncuran server aplikasi Anda.
Mengonfigurasi server
Anda memiliki beberapa opsi untuk menjalankan server web. Di akhir file Python Anda, tambahkan salah satu hal berikut:
localhost
tidak aman. Perhatikan bahwa tindakan ini cocok untuk pengujian langsung di jendela browser saja; domain yang tidak aman tidak dapat dimuat di iframe add-on Classroom.if __name__ == "__main__": # Disable OAuthlib's HTTPs verification. os.environ["OAUTHLIB_INSECURE_TRANSPORT"] = "1" # Run the web app at http://localhost:5000. app.run(debug=True)
Amankan
localhost
. Anda harus menentukan tuple file kunci SSL untuk argumenssl_context
.if __name__ == "__main__": # Run the web app at https://localhost:5000. app.run(host="localhost", ssl_context=("localhost.pem", "localhost-key.pem"), debug=True)
Server Gunicorn. Ini cocok untuk server siap produksi atau deployment cloud. Sebaiknya tetapkan variabel lingkungan
PORT
untuk digunakan dengan opsi peluncuran ini.if __name__ == "__main__": # Run the web app at https://<your domain>:<server_port>. # Defaults to https://<your domain>:8080. server_port = os.environ.get("PORT", "8080") app.run(debug=True, port=server_port, host="0.0.0.0")
Meluncurkan server
Jalankan aplikasi Python Anda untuk meluncurkan server seperti yang dikonfigurasi pada langkah sebelumnya.
python main.py
Klik URL yang muncul untuk melihat aplikasi web Anda di browser guna mengonfirmasi bahwa aplikasi tersebut berjalan dengan benar.
Node.js
Mengonfigurasi server
Untuk menjalankan server melalui HTTPS, Anda harus membuat sertifikat mandiri
yang digunakan untuk menjalankan aplikasi melalui HTTPS. Kredensial ini harus disimpan sebagai sslcert/cert.pem
dan sslcert/key.pem
di folder root repositori. Anda mungkin perlu menambahkan kunci ini ke rantai kunci OS agar
browser dapat menerimanya.
Pastikan *.pem
ada dalam file .gitignore
karena Anda tidak ingin meng-commit file tersebut ke git.
Meluncurkan server
Anda dapat menjalankan aplikasi dengan perintah berikut yang menggantikan step01
untuk langkah benar yang ingin Anda jalankan sebagai server (misalnya, step01
untuk 01-basic-app dan step02
untuk 02-sign-in).
npm run step01
atau
npm run step02
Tindakan ini akan meluncurkan server web pada https://localhost:5000
.
Anda dapat menghentikan server dengan Control + C
di terminal Anda.
Java
Mengonfigurasi server
Untuk menjalankan server melalui HTTPS, Anda harus membuat sertifikat mandiri yang digunakan untuk menjalankan aplikasi melalui HTTPS.
Pertimbangkan untuk menggunakan mkcert untuk pengembangan lokal.
Setelah Anda menginstal mkcert
, perintah berikut akan menghasilkan sertifikat yang disimpan secara lokal
untuk dijalankan melalui HTTPS.
mkcert -install
mkcert -pkcs12 -p12-file <path_to_keystore> <domain_name>
Contoh ini menyertakan file keystore di direktori resource. Anda dapat
menyimpannya di mana saja, tetapi pastikan Anda memperbarui
file application.properties
dengan jalur yang sesuai. Nama domain adalah domain tempat Anda menjalankan project (misalnya, localhost
).
Pastikan *.p12
ada dalam file .gitignore
karena Anda tidak ingin meng-commit file tersebut ke git.
Meluncurkan server
Luncurkan server dengan menjalankan metode main
pada file
Application.java
. Misalnya, di IntelliJ, Anda dapat mengklik kanan
Application.java
> Run 'Application'
di
direktori src/main/java/com/addons/spring
atau membuka file Application.java
untuk mengklik panah hijau di sebelah kiri tanda tangan
metode main(String[] args)
. Atau, Anda dapat menjalankan project di jendela
terminal:
./mvnw spring-boot:run
atau di Windows:
mvnw.cmd spring-boot:run
Tindakan ini akan meluncurkan server pada https://localhost:5000
atau pada port yang Anda tentukan di application.properties
.