Add-on Google Classroom kini tersedia secara umum untuk developer. Lihat dokumentasi add-on untuk informasi selengkapnya.

Halaman ini diterjemahkan oleh Cloud Translation API.

Panduan

Serangkaian panduan ini menggambarkan semua aspek pergerakan dari suatu pekerjaan add-on Classroom. Setiap langkah panduan membahas konsep, dan menerapkannya ke dalam satu aplikasi web. Tujuannya adalah untuk membantu Anda dalam menyiapkan, mengkonfigurasi, dan meluncurkan add-on yang fungsional.

Add-on Anda harus berinteraksi dengan project Google Cloud. Jika Anda tidak terbiasa dengan Google Cloud, sebaiknya baca Panduan Memulai. Anda mengelola kredensial, akses API, dan Google Workspace Marketplace SDK di Konsol Google Cloud Anda. Untuk informasi selengkapnya tentang Marketplace SDK, kunjungi Google Workspace Marketplace listingan Anda.

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 untuk 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 pemrograman dan dasar-dasar web konsep pengembangan. Sebaiknya baca artikel Konfigurasi project sebelum memulai panduan. Halaman ini berisi informasi penting detail konfigurasi yang tidak sepenuhnya dibahas dalam panduan.

Contoh penerapan

Contoh referensi lengkap tersedia di Python. Implementasi sebagian juga tersedia di Java dan Node.js. Implementasi ini adalah sumber kode contoh yang ditemukan di halaman berikutnya.

Tempat mendownload

Contoh Python dan Java tersedia di repositori GitHub:

Contoh Node.js dapat didownload sebagai file ZIP:

Arsip Node.js

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 di dalamnya iframe add-on.

Dimungkinkan untuk menggunakan localhost dengan sertifikat SSL; pertimbangkan mkcert jika Anda harus 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 ringkasan hal-hal yang diperlukan langkah-langkah untuk memulai. Kursus Menyiapkan project Google Cloud dalam panduan pertama, juga melakukan langkah-langkah konfigurasi khusus tindakan yang harus diambil.

Setelah selesai, download Client ID OAuth 2.0 Anda sebagai file JSON; Anda perlu menambahkan file kredensial ini ke direktori contoh yang diekstrak. Lihat Memahami untuk lokasi tertentu.

Kredensial OAuth

Ikuti langkah-langkah berikut untuk membuat kredensial OAuth baru:

Buka halaman Kredensial Google Cloud. Pastikan Anda memilih proyek yang tepat di bagian atas layar.
Klik BUAT KREDENSIAL dan pilih OAuth client ID dari drop-down.
Di halaman berikutnya:
- Setel Application type ke Web application.
- Di bagian URI pengalihan yang diotorisasi, klik TAMBAHKAN URI. Tambahkan lengkap path untuk rute callback bagi aplikasi Anda. Misalnya, https://my.domain.com/auth-callback atau https://localhost:5000/callback. Anda membuat dan menangani rute ini dalam panduan ini nanti. Anda dapat mengedit atau menambahkan rute tersebut lainnya kapan saja.
- Klik BUAT.
Kemudian, Anda akan menerima dialog berisi kredensial yang baru dibuat. Pilih DOWNLOAD JSON. Salin file JSON yang didownload ke server Anda saat ini.

Prasyarat spesifik bahasa

Lihat file README di setiap repositori untuk mengetahui daftar terbaru prasyarat.

Python

Contoh Python kita menggunakan framework Flask. Anda dapat mendownload kode sumber lengkap dari link yang disediakan.

Jika perlu, instal Python 3.7+ dan pastikan pip tersedia.

python3 -m ensurepip --upgrade

Sebaiknya siapkan dan aktifkan virtual Python baru lingkungan fleksibel App Engine.

python3 -m venv .classroom-addon-env
source .classroom-addon-env/bin/activate

Terdapat requirements.txt di setiap subdirektori panduan di bagian contoh yang diunduh. Anda dapat dengan cepat menginstal pustaka yang dibutuhkan menggunakan pip. Gunakan perintah berikut untuk menginstal library yang diperlukan untuk panduan pertama kami.

cd flask/01-basic-app
pip install -r requirements.txt

Node.js

Contoh Node.js kami menggunakan framework Express. Anda dapat mendownload kode sumber lengkap dari link yang disediakan.

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 mendownload kode sumber lengkap dari link yang disediakan.

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 berhasil tanpa mengharuskan Anda menginstal Maven itu sendiri.

Dalam direktori tempat Anda mendownload atau membuat 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 repositori berisi beberapa direktori yang namanya dimulai dengan angka, misalnya /01-basic-app/. Angka tersebut sesuai dengan langkah-langkah panduan tertentu. Setiap direktori berisi aplikasi web yang berfungsi penuh dan mengimplementasikan fitur tersebut. yang dijelaskan dalam panduan tertentu. Misalnya, /01-basic-app/ berisi implementasi akhir untuk aktivitas Create an add-on panduan kami.

Konten direktori

Konten direktori berbeda-beda bergantung pada bahasa penerapan:

Python

Root direktori berisi file berikut:
- main.py - titik entri aplikasi Python. Menentukan server konfigurasi yang ingin Anda gunakan dalam file ini, kemudian jalankan ke memulai server.
- requirements.txt - modul Python yang diperlukan untuk menjalankan aplikasi web. Aset ini dapat diinstal otomatis menggunakan pip install -r requirements.txt.
- client_secret.json - file rahasia klien yang didownload dari Google yang dihosting di Google Cloud. Perhatikan bahwa ini tidak termasuk dalam arsip contoh; Anda harus mengganti nama dan menyalin file kredensial yang diunduh ke masing-masing root direktori.
  
  Penting: Anda harus memberikan file rahasia klien dari project Google Cloud Anda sebelum Anda 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 gambar, CSS, dan JavaScript tambahan .
routes.py - metode pengendali untuk rute aplikasi web.
__init__.py - penginisialisasi untuk modul webapp. Ini penginisialisasi memulai server Flask dan memuat opsi konfigurasi ditetapkan di config.py.
File tambahan seperti yang diwajibkan oleh langkah panduan tertentu.

Node.js

Setiap langkah panduan dapat ditemukan di <step>-nya sendiri sub-folder. 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 servernya adalah ./<step>/app.js.

Java

Direktori project mencakup hal-hal berikut:

Direktori src.main berisi kode sumber dan konfigurasi yang akan dijalankan aplikasi berhasil. Direktori ini mencakup hal-hal berikut: + Direktori java.com.addons.spring berisi File Application.java dan Controller.java. Tujuan File Application.java bertanggung jawab untuk menjalankan server aplikasi sementara file Controller.java menangani logika endpoint. + Direktori resources berisi direktori templates dengan HTML dan JavaScript. File 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 di direktori resources. Anda dapat menyimpannya di mana pun Anda berada diinginkan, tetapi pastikan Anda mengupdate application.properties file 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, ini adalah secrets/*.p12 (tujuan keystore akan dibahas di bagian bawah). Untuk panduan 2 dan luar, Anda juga harus menyertakan jalur menuju client_secret.json untuk memastikan bahwa Anda tidak menyertakan secret dalam repositori jarak jauh. Untuk panduan 3 dan selanjutnya, Anda harus menambahkan jalur ke file {i>database<i} H2 dan file datastore pabrik. Informasi lebih lanjut tentang pengaturan penyimpanan data ini dapat Anda yang ada dalam panduan ketiga tentang menangani kunjungan berulang.
- mvnw dan mvnw.cmd adalah wrapper Maven yang dapat dieksekusi untuk Unix dan Windows. Misalnya, menjalankan ./mvnw --version di Unix menghasilkan versi Apache Maven, di antara informasi lainnya.
- Direktori .mvn berisi konfigurasi untuk wrapper Maven.

Menjalankan server contoh

Anda harus meluncurkan server untuk mengujinya. Ikuti petunjuk berikut untuk jalankan server contoh dalam bahasa pilihan Anda:

Python

Kredensial OAuth

Buat dan download kredensial OAuth Anda seperti yang dijelaskan sebelumnya. Letakkan file JSON di direktori {i>root<i} bersama dengan server aplikasi file peluncuran.

Mengonfigurasi server

Anda memiliki beberapa opsi untuk menjalankan server web. Di akhir Python, tambahkan salah satu dari berikut ini:

localhost tidak aman. Perhatikan bahwa ini cocok untuk pengujian secara langsung hanya di jendela browser; 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)

Gunicorn. Ini cocok untuk server siap produksi atau deployment cloud. Sebaiknya tetapkan variabel lingkungan PORT untuk gunakan 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 telah dikonfigurasi di langkah sebelumnya.

python main.py

Klik URL yang muncul untuk melihat aplikasi web Anda di browser untuk mengonfirmasi bahwa sudah berjalan dengan benar.

Node.js

Mengonfigurasi server

Untuk menjalankan server melalui HTTPS, Anda perlu membuat sertifikat mandiri yang digunakan untuk menjalankan aplikasi melalui HTTPS. Kredensial ini harus disimpan sebagai sslcert/cert.pem dan sslcert/key.pem di root repositori folder tersebut. Anda mungkin perlu menambahkan kunci ini ke rantai kunci OS Anda untuk browser Anda untuk menerimanya.

Pastikan *.pem ada dalam file .gitignore karena Anda tidak ingin untuk melakukan commit file 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 aplikasi 01-basic dan step02 untuk login 02).

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 perlu membuat sertifikat mandiri yang digunakan untuk menjalankan aplikasi melalui HTTPS.

Pertimbangkan untuk menggunakan mkcert untuk pengembangan lokal. Setelah Anda menginstal mkcert, perintah berikut menghasilkan sertifikat yang disimpan secara lokal untuk dijalankan dengan HTTPS.

mkcert -install
mkcert -pkcs12 -p12-file <path_to_keystore> <domain_name>

Contoh ini menyertakan file keystore di direktori resource. Anda mungkin menyimpannya di mana pun Anda mau, tetapi pastikan Anda memperbarui application.properties dengan jalur yang sesuai. Nama domainnya adalah domain tempat Anda menjalankan project (misalnya, localhost).

Pastikan *.p12 ada dalam file .gitignore karena Anda tidak ingin untuk melakukan commit file ke git.

Meluncurkan server

Luncurkan server dengan menjalankan metode main di Application.java . Di IntelliJ, misalnya, Anda dapat mengklik kanan Application.java > Run 'Application' di Direktori src/main/java/com/addons/spring atau buka Application.java untuk mengklik panah hijau di sebelah kiri main(String[] args) tanda tangan metode. Atau, Anda dapat menjalankan project di terminal periode:

./mvnw spring-boot:run

atau di Windows:

mvnw.cmd spring-boot:run

Tindakan ini akan meluncurkan server di https://localhost:5000 atau pada port yang Anda yang ditentukan di application.properties.