建立 Classroom 外掛程式

這是 Classroom 外掛程式的首次逐步操作說明 這一系列的影片

在這份逐步操作說明中,您將瞭解開發網頁應用程式及 以 Classroom 外掛程式的形式發布。未來逐步操作說明 展開這個應用程式。

在這份逐步操作說明中,您將完成下列步驟:

  • 為外掛程式建立新的 Google Cloud 專案。
  • 建立一個含有預留位置登入按鈕的骨架網頁應用程式。
  • 發布外掛程式的 Google Workspace Marketplace 商店資訊。

完成後,您可以安裝外掛程式 Classroom 外掛程式 iframe。

必要條件

選擇語言以查看適當的先決條件:

Python

Python 範例使用 Flask 架構。您可以下載 「總覽」頁面上所有逐步操作說明的原始碼。這段程式碼的程式碼 您可以在 /flask/01-basic-app/ 目錄中找到特別的逐步操作說明。

如有需要,請安裝 Python 3.7+,並確保 pip 可用。

python -m ensurepip --upgrade

我們也建議您設定並啟用新的 Python 虛擬版 環境。

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

下載範例中的每個逐步操作說明子目錄都包含 requirements.txt。您可以使用 pip。請使用下列指令安裝此憑證所需的程式庫

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

Node.js

Node.js 範例使用 Express 架構。您可以下載 完整原始碼

視需要安裝 NodeJS v16.13+

使用 npm 安裝必要節點模組。

npm install

Java

Java 範例使用 Spring Boot 架構。您可以下載 「總覽」頁面上所有逐步操作說明的完整原始碼

安裝 Java 11+ (如果尚未安裝在機器上)。

Spring Boot 應用程式可以使用 Gradle 或 Maven 處理建構作業和管理作業 依附元件這個範例包含 Maven 包裝函式,可確保 您完全不需要安裝 Maven

如要執行我們提供的範例,請在 下載專案,確保有 執行專案的必要條件

java --version
./mvnw --version

或在 Windows 執行下列指令:

java -version
mvnw.cmd --version

設定 Google Cloud 專案

Classroom API 存取權和必要的驗證方法 是由 Google Cloud 專案控管下列操作說明會引導您完成 建立及設定新專案,以用於 外掛程式。

建立專案

前往專案建立頁面,建立新的 Google Cloud 專案。你可以 為新專案提供任意名稱點選「Create」(建立)

新專案可能需要一點時間才能完整建立。完成後 請務必選取專案。您可在專案選取器中選擇 下拉式選單,或在頁面頂端按一下「選取專案」 畫面右上方的通知選單

在 Google Cloud 中選取專案
主控台

將 Google Workspace Marketplace SDK 附加至 Google Cloud 專案

前往 API 程式庫瀏覽器。搜尋 Google Workspace Marketplace SDK。這個 SDK 應該會顯示在 也就是預測結果

Google Workspace Marketplace SDK
卡牌

選取 Google Workspace Marketplace SDK 資訊卡,然後按一下「啟用」

設定 Google Workspace Marketplace SDK

Google Workspace Marketplace 提供的產品資訊 管理員會安裝您的外掛程式。設定 Marketplace SDK 的應用程式設定商店 清單OAuth 同意畫面可以繼續操作。

應用程式設定

前往 Marketplace 的 SDK 的「App Configuration」(應用程式設定) 頁面。 提供下列資訊:

  • 將「App Visibility」設為 PublicPrivate

    • 這個公開設定適用於日後即將發布的應用程式 提供給使用者公開應用程式必須先經過核准程序才能獲得核准 發布版本,但您可以指定能 將其視為草稿測試。這是發布前的狀態 進行測試及開發,再送交核准。
    • 私人設定適用於內部測試和開發。A 罩杯 私人應用程式只能由 已建立專案。因此,建議您將瀏覽權限設為「私人」 前提是專案必須在使用 Google Workspace for Education 的網域中建立 訂閱,否則測試使用者無法啟動 Classroom 外掛程式。
    ,瞭解如何調查及移除這項存取權。
  • 視需要將「安裝設定」設為 Admin Only install。 僅限網域管理員安裝。

  • 在「App Integration」下方,選取「Classroom 外掛程式」。您 系統提示您輸入 secure 連結設定 URI;這是您的網址 系統預期會在使用者開啟您的外掛程式時載入。為了便於 此範例應為 https://<your domain>/addon-discovery

  • 允許的附件 URI 前置字串可用來驗證 AddOnAttachment 使用 courses.*.addOnAttachments.createcourses.*.addOnAttachments.patch 方法。驗證是一種常值 字串前置字元相符,因此在這個情況下無法使用萬用字元 讓應用程式從可以最快做出回應的位置 回應使用者要求至少添加內容伺服器的根網域,例如 https://localhost:5000/https://cdn.myedtech.com/

  • 加入您在 OAuth 同意畫面中提供的同一個 OAuth 範圍: 先前的步驟

  • 在「開發人員」底下依貴機構需求填寫欄位 連結

商店資訊

前往 Marketplace SDK 的「商店資訊」頁面。 提供下列資訊:

  • 在「應用程式詳細資料」下方新增語言,或展開 文字。提供應用程式名稱和說明。這些 會顯示在外掛程式的 Google Workspace Marketplace 商店資訊頁面。 按一下「完成」即可儲存。
  • 選擇外掛程式的「類別」
  • 在「圖像資產」下方,為必填欄位提供圖片。這類員工 稍後可以變更,不過目前可以是預留位置。
  • 在「支援連結」下方,提供要求的網址。您可以輸入 但如果您想將應用程式設為「私人」 採用

如果您在上個步驟中將應用程式瀏覽權限設為「私人」,請按一下 PUBLISH;您的應用程式便可立即供安裝。如果將 應用程式瀏覽權限設為「公開」,請在「草稿測試人員」區域中新增電子郵件地址 ,然後按一下「儲存草稿」

當使用者首次授權您的應用程式時,就會顯示 OAuth 同意畫面。提示 允許您的應用程式存取個人資料和帳戶資訊, 由你啟用的範圍發出。

前往「OAuth 同意畫面」建立頁面。提供下列資訊 每個 ACL 都由一或多個項目組成 而這些項目包含兩項資訊

  • 將「使用者類型」設為「外部」。點選「建立」
  • 在下一頁中,填入必要的應用程式詳細資料和聯絡資訊。 在「授權網域」底下提供代管您應用程式的所有網域。按一下 儲存並繼續
  • 新增網頁應用程式所需的任何 OAuth 範圍。詳情請參閱 OAuth 設定指南,以便深入討論範圍及其用途。

    您至少必須要求下列其中一個範圍,Google 才能 傳送 login_hint 查詢參數。進一步說明 如要瞭解 OAuth 設定指南,請參閱:

    • https://www.googleapis.com/auth/userinfo.email (已隨附)
    • https://www.googleapis.com/auth/userinfo.profile (已隨附)

    以下是 Classroom 外掛程式的專屬範圍:

    • https://www.googleapis.com/auth/classroom.addons.teacher
    • https://www.googleapis.com/auth/classroom.addons.student

    請一併納入應用程式所需的其他 Google API 範圍 使用者。

    按一下 [儲存並繼續]。

  • 在「測試使用者」頁面上,列出所有測試帳戶的電子郵件地址。 按一下「儲存並繼續」

確認您的設定正確無誤,然後返回數字面板。

安裝外掛程式

現在可以透過畫面頂端的連結安裝外掛程式 Marketplace SDK 的「商店資訊」頁面。按一下應用程式圖示 查看頁面頂端,然後選擇「安裝」

建構基本網頁應用程式

設定包含兩條路徑的基本架構網頁應用程式。未來逐步操作說明 展開此應用程式,目前只需建立外掛程式的到達網頁 我們為「公司網站」建立 /addon-discovery 和模擬索引頁面 /

iframe 中的網頁應用程式範例

實作這兩個端點:

  • /:顯示歡迎訊息和關閉目前分頁的按鈕 以及附加的 iframe
  • /addon-discovery:顯示歡迎訊息和兩個按鈕:一個用於關閉 外掛程式 iframe,以及一個用於在新分頁中開啟網站。

請注意,我們即將新增用來建立及關閉視窗或 iframe 的按鈕。這些 示範可將使用者安全地彈出在新分頁中 請繼續閱讀本指南

建立公用程式指令碼

建立 static/scripts 目錄。建立新檔案 addon-utils.js。將 有兩個函式

/**
 *   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, 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',
  }, '*');
};

建立路徑

實作 /addon-discovery/ 端點。

Python

設定應用程式目錄

就這個範例的目的而言,將應用程式邏輯建構為 Python 模組。這是我們提供的範例中的 webapp 目錄。

為伺服器模組 webapp 建立目錄,例如。移動 static 目錄複製到模組目錄中。建立 template 目錄 列在模組目錄中HTML 檔案放在這裡。

建構伺服器模組*

在模組目錄中建立 __init__.py 檔案,並新增下列指令 匯入和宣告

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

然後建立檔案來處理網頁應用程式的路徑。這是 webapp/routes.py。依序實作 檔案。

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.")

請注意,我們的路徑都會將 message 變數傳遞至各自的對應 Jinja 範本。這有助於識別使用者到達的網頁。

建立設定和啟動檔案

在應用程式的根目錄中,建立 main.pyconfig.py 檔案。在 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."

main.py 檔案中匯入模組,並啟動 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

路徑是以下列幾行登錄在 app.js 檔案中。

const websiteRouter = require('./routes/index');
const addonRouter = require('./routes/classroom-addon');

app.use('/', websiteRouter);
app.use('/addon-discovery', addonRouter);

開啟 /01-basic-app/routes/index.js 並檢查程式碼。這條路線是 也就是使用者造訪公司網站時達到的目標。路徑會將 使用 index 握把範本回應,並將一個 包含 titlemessage 變數的資料物件。

router.get('/', function (req, res, next) {
  res.render('index', {
    title: 'Education Technology',
    message: 'Welcome to our website!'
  });
});

開啟第二條路線/01-basic-app/routes/classroom-addon.js並檢查 程式碼使用者造訪外掛程式後,就能抵達這個路線。通知 此路徑使用 discovery 握把範本,另外還有 addon.hbs 版面配置,以不同於公司的方式顯示網頁 網站。

router.get('/', function (req, res, next) {
  res.render('discovery', {
    layout: 'addon.hbs',
    title: 'Education Technology Classroom add-on',
    message: `Welcome.`
  });
});

Java

Java 程式碼範例會使用模組封裝依序逐步操作說明 100 萬步的訓練由於這是第一段逐步操作說明,程式碼位於 step_01_basic_app 模組。因此不一定要將 透過模組建構專案因此建議您在單一專案中建構產品 也可以按步驟操作

在本範例專案中,建立控制器類別 Controller.java,以便達到以下目的: 並定義端點在此檔案中匯入 @GetMapping 註解: spring-boot-starter-web 依附元件。

import org.springframework.web.bind.annotation.GetMapping;

在類別上方加入 Spring 架構控制器註解 指出類別用途。

@org.springframework.stereotype.Controller
public class Controller {

然後實作兩個路徑以及其他錯誤處理路徑。

/** 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";
}

測試外掛程式

啟動伺服器。接下來,以他人身分登入 Google Classroom老師的測試使用者。前往「課堂作業」分頁並建立新項目 轉讓。從「外掛程式」挑選器中選取外掛程式。iframe 會隨即開啟 這個外掛程式就會載入您在附件設定 URI Marketplace SDK 的「App Configuration」頁面。

恭喜!您可以繼續進行下一個步驟:登入使用者 使用 Google 單一登入 (SSO) 服務