Halaman ini diterjemahkan oleh Cloud Translation API.

Panduan

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 atau https://localhost:5000/callback. Anda akan membuat dan menangani rute ini nanti dalam panduan ini. Anda dapat mengedit atau menambahkan rute lainnya kapan saja.
- Klik CREATE.
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 menggunakan pip 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.
  
  Penting: Anda harus memberikan file rahasia klien dari project Google Cloud sebelum dapat menjalankan contoh.
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 modul webapp. Inisialisasi ini memulai server Flask dan memuat opsi konfigurasi yang ditetapkan di config.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 file Application.java dan Controller.java. File Application.java bertanggung jawab untuk menjalankan server aplikasi sementara file Controller.java menangani logika endpoint. + direktori resources berisi direktori templates dengan file HTML dan JavaScript. Objek ini juga berisi file application.properties yang menentukan port untuk menjalankan server, jalur ke file keystore, dan jalur ke direktori templates. Contoh ini menyertakan file keystore dalam direktori resources. Anda dapat menyimpannya di mana saja, tetapi pastikan Anda mengupdate file application.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 adalah secrets/*.p12 (tujuan keystore dibahas di bagian di bawah). Untuk panduan 2 dan selanjutnya, Anda juga harus menyertakan jalur ke file client_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 dan mvnw.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 argumen ssl_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:3000.

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.