Halaman ini diterjemahkan oleh Cloud Translation API.

Membuat add-on Classroom

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.

Pilih project di Google Cloud Console

Melampirkan GWM SDK ke project Google Cloud

Buka browser Library API. Telusuri Google Workspace Marketplace SDK. Anda akan melihat SDK muncul dalam daftar hasil.

Kartu Google Workspace Marketplace SDK

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. Pilih Public hanya jika Anda sudah siap agar add-on Anda digunakan oleh masyarakat umum.

Peringatan: Pastikan setelan Visibilitas Aplikasi Anda sudah benar sebelum menyimpan. Anda tidak dapat mengubah Visibilitas Aplikasi setelah ditetapkan. Anda harus membuat project Google Cloud baru untuk menetapkan Visibilitas Aplikasi yang berbeda.
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 metode courses.*.addOnAttachments.create dan courses.*.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.

Peringatan: Add-on Anda tidak dapat dipublikasikan jika Konfigurasi Aplikasi menentukan cakupan yang berbeda dari yang tercantum di layar izin OAuth Anda.
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".

Contoh aplikasi web di iframe

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.