Ini adalah panduan pertama dalam seri panduan add-on Classroom.
Dalam panduan ini, Anda meletakkan dasar untuk mengembangkan aplikasi web dan memublikasikannya sebagai add-on Classroom. Langkah panduan mendatang akan memperluas aplikasi ini.
Dalam kursus ini, Anda akan menyelesaikan hal-hal berikut:
- Membuat project Google Cloud baru untuk aplikasi web Anda.
- Membuat aplikasi web kerangka dengan tombol login placeholder.
- Memublikasikan Listingan Play Store Google Workspace Marketplace (GWM) pribadi untuk aplikasi web Anda.
Setelah selesai, Anda dapat menginstal add-on dan memuatnya ke iframe add-on Classroom.
Prasyarat
Pilih bahasa di bawah untuk melihat prasyarat yang sesuai:
Python
Contoh Python kita menggunakan framework Flask.
Anda dapat mendownload kode sumber lengkap untuk semua panduan dari
halaman Ringkasan. Kode untuk panduan khusus ini dapat ditemukan di
direktori /flask/01-basic-app/
.
Jika perlu, instal Python 3.7+ dan pastikan
pip
tersedia.
python -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
Setiap subdirektori panduan dalam contoh yang didownload berisi
requirements.txt
. Anda dapat dengan cepat menginstal library yang diperlukan menggunakan
pip
. Gunakan hal berikut untuk menginstal library yang diperlukan untuk panduan
ini.
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 untuk semua panduan dari halaman Ringkasan.
Jika perlu, instal NodeJS v16.13+.
Instal modul node yang diperlukan menggunakan npm
.
npm install
Java
Contoh Java kami menggunakan framework Spring Boot. Anda dapat mendownload kode sumber lengkap untuk semua panduan dari halaman Ringkasan.
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.
Agar dapat menjalankan contoh yang kami sediakan, jalankan perintah berikut di direktori tempat Anda mendownload project guna memastikan Anda memiliki prasyarat untuk menjalankan project.
java --version
./mvnw --version
Atau di Windows:
java -version
mvnw.cmd --version
Menyiapkan project Google Cloud
Akses ke Classroom API dan metode autentikasi yang diperlukan dikontrol oleh project Google Cloud. Petunjuk berikut memandu Anda melakukan langkah-langkah minimum untuk membuat dan mengonfigurasi project baru untuk digunakan dengan add-on.
Mulai membuat project
Buat project Google Cloud baru dengan membuka halaman pembuatan project. Anda dapat memberikan nama apa pun untuk project baru. Klik Buat.
Perlu waktu beberapa saat hingga project baru selesai dibuat. Setelah selesai, pastikan untuk memilih project; Anda dapat memilihnya di menu drop-down pemilih project di bagian atas layar, atau mengklik PILIH PROJECT di menu notifikasi di kanan atas.
Melampirkan GWM SDK ke project Google Cloud
Buka browser Library API. Telusuri
Google Workspace Marketplace SDK
. Anda akan melihat SDK muncul dalam daftar
hasil.
Pilih kartu Google Workspace Marketplace SDK, lalu klik Aktifkan.
Mengonfigurasi GWM SDK
GWM menyediakan listingan tempat pengguna dan administrator menginstal add-on Anda. Konfigurasikan Layar Izin OAuth serta Konfigurasi Aplikasi dan Listingan Play Store GWM SDK untuk melanjutkan.
Layar Izin OAuth
Layar Izin OAuth akan muncul saat pengguna pertama kali memberikan otorisasi ke aplikasi Anda. Layar ini akan meminta mereka untuk mengizinkan aplikasi Anda mengakses informasi pribadi dan akun mereka, seperti yang ditentukan oleh cakupan yang Anda aktifkan.
Buka halaman pembuatan OAuth consent screen. Berikan informasi berikut:
- Tetapkan Jenis Pengguna ke Eksternal. Klik Buat.
- Di halaman berikutnya, isi detail aplikasi dan informasi kontak yang diperlukan. Cantumkan domain apa pun yang menghosting aplikasi Anda di bagian Domain yang Diotorisasi. Klik SIMPAN DAN LANJUTKAN.
Tambahkan Cakupan OAuth yang diperlukan aplikasi web Anda. Lihat panduan konfigurasi OAuth untuk pembahasan mendalam tentang cakupan dan tujuannya.
Anda harus meminta minimal salah satu cakupan berikut agar Google dapat mengirimkan parameter kueri
login_hint
. Penjelasan yang lebih terperinci tentang perilaku ini tersedia di panduan konfigurasi OAuth kami:https://www.googleapis.com/auth/userinfo.email
(sudah disertakan)https://www.googleapis.com/auth/userinfo.profile
(sudah disertakan)
Cakupan berikut khusus untuk add-on Classroom:
https://www.googleapis.com/auth/classroom.addons.teacher
https://www.googleapis.com/auth/classroom.addons.student
Sertakan juga cakupan Google API lainnya yang diperlukan aplikasi Anda dari pengguna akhir.
Klik SIMPAN DAN LANJUTKAN.
Cantumkan alamat email akun pengujian di halaman Pengguna pengujian. Klik SIMPAN DAN LANJUTKAN.
Pastikan setelan Anda sudah benar, lalu kembali ke dasbor.
Konfigurasi Aplikasi
Buka halaman App Configuration di GWM SDK. Berikan informasi berikut:
Setel Visibilitas Aplikasi ke
Private
. Setelan ini sesuai untuk tujuan pengujian dan pengembangan, serta merupakan pilihan yang tepat untuk panduan ini. PilihPublic
hanya jika Anda sudah siap agar add-on Anda digunakan oleh masyarakat umum.Setel Installation Settings ke
Admin Only install
jika Anda ingin membatasi penginstalan ke administrator domain.Di bagian Integrasi Aplikasi, pilih add-on Classroom. Anda akan diminta untuk memberikan URI Penyiapan Lampiran yang aman; yaitu URL yang diharapkan untuk dimuat saat pengguna membuka add-on. Untuk tujuan panduan ini, ID harus berupa
https://<your domain>/addon-discovery
.Awalan URI Lampiran yang Diizinkan digunakan untuk memvalidasi URI yang ditetapkan di
AddOnAttachment
menggunakan metodecourses.*.addOnAttachments.create
dancourses.*.addOnAttachments.patch
. Validasi adalah pencocokan awalan string literal dan tidak mengizinkan penggunaan karakter pengganti untuk saat ini. Untuk saat ini, Anda dapat membiarkannya kosong.Tambahkan Cakupan OAuth yang sama seperti yang diberikan di layar izin OAuth Anda di langkah sebelumnya.
Isi kolom yang sesuai untuk organisasi Anda di bagian Link Developer.
Listingan Store
Buka halaman Listingan Play Store GWM SDK. Berikan informasi berikut:
- Di bagian Detail Aplikasi, tambahkan bahasa atau luaskan drop-down di samping bahasa yang sudah tercantum. Berikan Nama Aplikasi dan deskripsi yang akan muncul di halaman listingan Play Store GWM add-on Anda. Klik Selesai untuk menyimpan.
- Pilih Kategori untuk add-on Anda.
- Di bagian Aset Grafik, berikan gambar untuk kolom yang wajib diisi. Visibilitas ini dapat diubah nanti, dan dapat menjadi placeholder jika Anda menetapkan Visibilitas Aplikasi ke Pribadi di langkah sebelumnya.
- Di bagian Link Dukungan, berikan URL yang diminta. URL ini dapat menjadi placeholder jika Anda menetapkan Visibilitas Aplikasi ke Pribadi di langkah sebelumnya.
Klik PUBLIKASIKAN untuk menyimpan setelan. Jika Anda menetapkan Visibilitas Aplikasi ke Pribadi di langkah sebelumnya, aplikasi Anda akan langsung tersedia untuk diinstal. Jika Anda menyetel Visibilitas Aplikasi ke Publik, aplikasi Anda akan dikirim untuk ditinjau oleh tim GWM sebelum dapat disediakan untuk diinstal.
Instal add-on
Kini Anda dapat menginstal add-on menggunakan link di bagian atas halaman Listingan Play Store GWM SDK. Klik URL Aplikasi di bagian atas halaman untuk melihat listingan, lalu pilih Instal.
Membangun aplikasi web dasar
Menyiapkan aplikasi web kerangka dengan dua rute. Langkah panduan mendatang
akan memperluas aplikasi ini, jadi untuk saat ini cukup buat halaman landing untuk add-on
/addon-discovery
dan halaman indeks tiruan /
untuk "situs perusahaan".
Terapkan kedua endpoint ini:
/
: menampilkan pesan selamat datang dan tombol untuk menutup tab saat ini dan iframe add-on./addon-discovery
: menampilkan pesan selamat datang dan dua tombol: satu untuk menutup iframe add-on dan satu lagi untuk membuka situs di tab baru.
Perhatikan bahwa kami menambahkan tombol untuk membuat dan menutup jendela atau iframe. Ini menunjukkan metode untuk memunculkan pengguna dengan aman ke tab baru untuk otorisasi dalam panduan berikutnya.
Buat skrip utilitas
Buat direktori static/scripts
. Buat file baru addon-utils.js
. Tambahkan dua fungsi berikut.
/**
* Opens a given destination route in a new window. This function uses
* window.open() so as to force window.opener to retain a reference to the
* iframe from which it was called.
* @param {string} destinationURL The endpoint to open, or "/" if none is
* provided.
*/
function openWebsiteInNewTab(destinationURL = '/') {
window.open(destinationURL, '_blank');
}
/**
* Close the iframe by calling postMessage() in the host Classroom page. This
* function can be called directly when in a Classroom add-on iframe.
*
* Alternatively, it can be used to close an add-on iframe in another window.
* For example, if an add-on iframe in Window 1 opens a link in a new Window 2
* using the openWebsiteInNewTab function above, you can call
* window.opener.closeAddonIframe() from Window 2 to close the iframe in Window
* 1.
*/
function closeAddonIframe() {
window.parent.postMessage({
type: 'Classroom',
action: 'closeIframe',
}, '*');
};
Membuat rute
Terapkan endpoint /addon-discovery
dan /
.
Python
Menyiapkan direktori aplikasi
Untuk tujuan contoh ini, buat struktur logika aplikasi sebagai
modul Python. Ini adalah direktori webapp
dalam contoh yang diberikan.
Buat direktori untuk modul server, misalnya webapp
. Pindahkan
direktori static
ke direktori modul. Buat juga direktori template
di direktori modul. File HTML Anda akan masuk di sini.
Membangun modul server*
Buat file __init__.py
di direktori modul Anda, lalu tambahkan impor dan deklarasi
berikut.
from flask import Flask
import config
app = Flask(__name__)
app.config.from_object(config.Config)
# Load other module script files. This import statement refers to the
# 'routes.py' file described below.
from webapp import routes
Kemudian buat file untuk menangani rute aplikasi web. Ini adalah webapp/routes.py
dalam contoh yang diberikan. Terapkan kedua rute tersebut dalam
file ini.
from webapp import app
import flask
@app.route("/")
def index():
return flask.render_template("index.html",
message="You've reached the index page.")
@app.route("/classroom-addon")
def classroom_addon():
return flask.render_template(
"addon-discovery.html",
message="You've reached the addon discovery page.")
Perhatikan bahwa rute kita meneruskan variabel message
ke template
Jinja-nya masing-masing. Hal ini berguna untuk mengidentifikasi halaman mana yang telah dibuka pengguna.
Membuat konfigurasi dan meluncurkan file
Dalam direktori utama aplikasi Anda, buat file main.py
dan config.py
. Konfigurasi kunci rahasia Anda di config.py
.
import os
class Config(object):
# Note: A secret key is included in the sample so that it works.
# If you use this code in your application, replace this with a truly secret
# key. See https://flask.palletsprojects.com/quickstart/#sessions.
SECRET_KEY = os.environ.get(
'SECRET_KEY') or "REPLACE ME - this value is here as a placeholder."
Dalam file main.py
, impor modul Anda dan mulai server Flask.
from webapp import app
if __name__ == "__main__":
# Run the application over HTTPs with a locally stored certificate and key.
# Defaults to https://localhost:5000.
app.run(
host="localhost",
ssl_context=("localhost.pem", "localhost-key.pem"),
debug=True)
Node.js
Rute didaftarkan dalam file app.js
dengan baris berikut.
const websiteRouter = require('./routes/index');
const addonRouter = require('./routes/classroom-addon');
app.use('/', websiteRouter);
app.use('/addon-discovery', addonRouter);
Buka /01-basic-app/routes/index.js
dan tinjau kodenya. Rute ini dijangkau saat pengguna akhir mengunjungi situs perusahaan. Rute merender
respons menggunakan template Handlebar index
dan meneruskan objek data
yang berisi variabel title
dan message
ke template.
router.get('/', function (req, res, next) {
res.render('index', {
title: 'Education Technology',
message: 'Welcome to our website!'
});
});
Buka rute kedua /01-basic-app/routes/classroom-addon.js
dan tinjau
kodenya. Rute ini dicapai saat pengguna akhir mengunjungi add-on. Perhatikan
bahwa rute ini menggunakan template Handlebar discovery
dan juga
tata letak addon.hbs
untuk merender halaman secara berbeda dengan situs
perusahaan.
router.get('/', function (req, res, next) {
res.render('discovery', {
layout: 'addon.hbs',
title: 'Education Technology Classroom add-on',
message: `Welcome.`
});
});
Java
Contoh kode Java menggunakan modul untuk mengemas langkah-langkah panduan
berurutan. Karena ini adalah panduan pertama, kode berada di bawah
modul step_01_basic_app
. Anda tidak diharapkan untuk mengimplementasikan project
menggunakan modul; tetapi, sebaiknya buat satu project
saat Anda mengikuti setiap langkah dalam panduan.
Buat class pengontrol, Controller.java
dalam project contoh ini, untuk menentukan endpoint. Dalam file ini, impor anotasi @GetMapping
dari
dependensi spring-boot-starter-web
.
import org.springframework.web.bind.annotation.GetMapping;
Sertakan anotasi pengontrol framework Spring di atas definisi class untuk menunjukkan tujuan class.
@org.springframework.stereotype.Controller
public class Controller {
Kemudian, terapkan dua rute dan rute tambahan untuk penanganan error.
/** Returns the index page that will be displayed when the add-on opens in a
* new tab.
* @param model the Model interface to pass error information that's
* displayed on the error page.
* @return the index page template if successful, or the onError method to
* handle and display the error message.
*/
@GetMapping(value = {"/"})
public String index(Model model) {
try {
return "index";
} catch (Exception e) {
return onError(e.getMessage(), model);
}
}
/** Returns the add-on discovery page that will be displayed when the iframe
* is first opened in Classroom.
* @param model the Model interface to pass error information that's
* displayed on the error page.
* @return the addon-discovery page.
*/
@GetMapping(value = {"/addon-discovery"})
public String addon_discovery(Model model) {
try {
return "addon-discovery";
} catch (Exception e) {
return onError(e.getMessage(), model);
}
}
/** Handles application errors.
* @param errorMessage message to be displayed on the error page.
* @param model the Model interface to pass error information to display on
* the error page.
* @return the error page.
*/
@GetMapping(value = {"/error"})
public String onError(String errorMessage, Model model) {
model.addAttribute("error", errorMessage);
return "error";
}
Menguji add-on
Luncurkan server Anda. Kemudian, login ke Google Classroom sebagai salah satu pengguna uji coba Pengajar Anda. Buka tab Tugas Kelas dan buat Tugas baru. Klik tombol Add-ons di bawah area teks, lalu pilih add-on Anda. iframe akan terbuka dan add-on akan memuat URI Penyiapan Lampiran yang Anda tentukan di halaman App Configuration di GWM SDK.
Selamat! Anda siap untuk melanjutkan ke langkah berikutnya: membuat pengguna login dengan SSO Google.