逐步操作說明

本系列逐步操作說明將詳細說明 Classroom 外掛程式的各項操作。每個逐步操作說明都會介紹特定概念，方便您在單一網頁應用程式中實作。目的是協助您設定、設定及啟動功能性外掛程式。

外掛程式必須與 Google Cloud 專案互動。如果您不熟悉 Google Cloud，建議您參閱入門指南。您可以在 Google Cloud 控制台中管理憑證、API 存取權和 Google Workspace Marketplace SDK。如要進一步瞭解 Marketplace SDK，請參閱「Google Workspace Marketplace 產品資訊」指南頁面。

本指南涵蓋下列主題：

  • 使用 Google Cloud 建立要以 iframe 顯示在 Classroom 中的頁面。
  • 新增 Google 單一登入 (SSO) 功能，並允許使用者登入。
  • 發出 API 呼叫，將外掛程式附加到作業中。
  • 符合主要的外掛程式提交規定和必要功能。

本指南假設您已熟悉程式設計和基本的網頁開發概念。強烈建議您先閱讀專案設定指南，再開始逐步操作說明。本頁含有部分不在逐步操作說明中的重要設定詳細資料。

實作範例

完整的參考範例請見 Python。Java 和 Node.js 中也提供部分實作項目。這些實作是後續頁面中的程式碼範例來源。

下載裝置

GitHub 存放區提供 Python 和 Java 範例：

您可以下載 Node.js 範例的 ZIP 檔案：

先備知識

請參閱下列章節，準備新的外掛程式專案。

HTTPS 憑證

儘管您可以在任何開發環境託管應用程式，但只有 https:// 才能使用 Classroom 外掛程式。因此，您需要採用 SSL 加密的伺服器，才能部署應用程式或在外掛程式 iframe 中進行測試。

您可以使用 localhost 搭配 SSL 憑證；如需為本機開發建立憑證，請考慮使用 mkcert。

Google Cloud 專案

您必須先設定 Google Cloud 專案，才能使用這些範例。請參閱「 Google Cloud 專案建立」指南，快速瞭解開始的必要步驟。第一篇逐步操作說明的「設定 Google Cloud 專案」一節也逐步說明您可以採取的特定設定動作。

完成後，請將 OAuth 2.0 用戶端 ID 下載為 JSON 檔案，且您必須將這個憑證檔案新增至解壓縮的範例目錄。請參閱「瞭解特定位置的檔案」一節。

OAuth 憑證

請按照下列步驟建立新的 OAuth 憑證：

  • 前往 Google Cloud Credentials 頁面。確認您已在畫面頂端選取正確的專案。
  • 按一下「CREATE CREDENTIALS」，然後在下拉式選單中選擇「OAuth client ID」。
  • 在下一頁中：
    • 將「應用程式類型」設為「網頁應用程式」。
    • 按一下「已授權的重新導向 URI」下方的「新增 URI」。新增應用程式的回呼路徑完整路徑。例如 https://my.domain.com/auth-callback 或 https://localhost:5000/callback。稍後在本逐步操作說明中，您會建立及處理這個路徑。您可以隨時編輯或新增更多這類路線。
    • 點按「建立」。
  • 接著，您會收到一封內含新建立憑證的對話方塊。選擇「Download JSON」(下載 JSON) 選項。將下載的 JSON 檔案複製到伺服器目錄。

特定程式語言的必備條件

如需最新的必備條件清單，請查看每個存放區中的 README 檔案。

Python

Python 範例使用 Flask 架構。您可以從提供的連結下載完整的原始碼。

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

python3 -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 架構。您可以從提供的連結中下載完整的原始碼。

這個範例需要 Node.js 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

瞭解檔案

以下各節說明範例目錄的版面配置。

目錄名稱

每個存放區都含有多個目錄，這些目錄的名稱開頭為數字，例如 /01-basic-app/。這些數字會對應至特定的逐步操作說明步驟。每個目錄都包含功能齊全的網頁應用程式，可實作特定逐步操作說明中所述的功能。舉例來說，/01-basic-app/ 目錄包含「建立外掛程式」逐步操作說明的最終實作項目。

目錄內容

目錄內容會因實作語言而異：

Python

  • 目錄根目錄包含下列檔案：

    • main.py：Python 應用程式進入點。指定您要在這個檔案中使用的伺服器設定，然後執行該設定來啟動伺服器。
    • requirements.txt：執行網頁應用程式所需的 Python 模組。可使用 pip install -r requirements.txt 自動安裝。

    • client_secret.json：從 Google Cloud 下載的用戶端密鑰檔案。請注意，範例封存中並未包含這項資訊；您應重新命名下載的憑證檔案，並將其複製到每個目錄根目錄。

  • config.py - Flask 伺服器的設定選項。

  • webapp 目錄包含網頁應用程式的內容。包含的內容如下：

  • /templates/ 目錄，內含多個網頁的 Jinja 範本。

  • 內含圖片、CSS 和輔助 JavaScript 檔案的 /static/ 目錄。

  • routes.py：網頁應用程式路徑的處理常式方法。

  • __init__.py：webapp 模組的初始化器。此初始化器會啟動 Flask 伺服器，並載入 config.py 中的設定選項集。

  • 特定逐步操作說明步驟所需的其他檔案。

Node.js

步行的每個步驟都可以在專屬的 <step> 子資料夾中找到。每個步驟都包含：

  • 您可以在 ./<step>/public 資料夾中找到 JavaScript、CSS 和圖片等靜態檔案。
  • 您可以在 ./<step>/routes 資料夾中找到 Express 路由器。
  • 您可以在 ./<step>/views 資料夾中找到 HTML 範本。
  • 伺服器應用程式為 ./<step>/app.js。

Java

專案目錄包含以下內容：

  • src.main 目錄包含原始碼和設定，可順利執行應用程式。這個目錄包含以下內容：+ java.com.addons.spring 目錄包含 Application.java 和 Controller.java 檔案。Application.java 檔案負責執行應用程式伺服器，Controller.java 檔案則會處理端點邏輯。+ resources 目錄包含含有 HTML 和 JavaScript 檔案的 templates 目錄。其中也包含 application.properties 檔案，用來指定執行伺服器的通訊埠、KeyStore 檔案的路徑，以及 templates 目錄的路徑。這個範例包括 resources 目錄中的 KeyStore 檔案。您可以將檔案儲存在任何所需位置，但請務必依據實際需求更新 application.properties 檔案。
    • pom.xml 包含建構專案及定義必要依附元件所需的資訊。
    • .gitignore 包含不應上傳至 Git 的檔案名稱。請務必在此 .gitignore 中新增 KeyStore 路徑。在提供的範例中為 secrets/*.p12 (KeyStore 的用途會在下一節討論)。如需逐步操作說明，您也應加入 client_secret.json 檔案的路徑，確保不會將密鑰納入遠端存放區。如需逐步操作說明 3 及後續操作，請在 H2 資料庫檔案和檔案資料儲存庫工廠中新增路徑。如要進一步瞭解如何設定這些資料儲存庫，請參閱「處理重複造訪」的第三份逐步操作說明。
    • mvnw 和 mvnw.cmd 是 Unix 和 Windows 的 Maven 包裝函式執行檔。例如，在 Unix 上執行 ./mvnw --version，會輸出 Apache Maven 版本及其他資訊。
    • .mvn 目錄包含 Maven 包裝函式的設定。

執行範例伺服器

您需要啟動伺服器才能進行測試。請按照下列操作說明以您選擇的語言執行範例伺服器：

Python

OAuth 憑證

按照上述說明建立及下載 OAuth 憑證。請將 JSON 檔案連同應用程式的伺服器啟動檔案一起放在根目錄中。

設定伺服器

執行網路伺服器的方法有幾種，在 Python 檔案結尾，新增下列其中一項：

  1. 未受保護的 localhost。請注意，這個方法僅適用於直接在瀏覽器視窗中進行測試，不安全的網域無法在 Classroom 外掛程式 iframe 中載入。

    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)

  2. 確保 localhost 安全。您必須為 ssl_context 引數指定 SSL 金鑰檔案的組合。

    if __name__ == "__main__":
  # Run the web app at https://localhost:5000.
  app.run(host="localhost",
          ssl_context=("localhost.pem", "localhost-key.pem"),
          debug=True)

  3. Gunicorn 伺服器。適合可用於實際工作環境的伺服器或雲端部署項目。建議您設定 PORT 環境變數，與這個啟動選項搭配使用。

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

啟動伺服器

執行 Python 應用程式，以在上一步的設定中啟動伺服器。

python main.py

按一下顯示的網址，即可在瀏覽器中檢視網頁應用程式，確認網頁應用程式可正常運作。

Node.js

設定伺服器

如要透過 HTTPS 執行伺服器，您必須建立自我憑證，用於透過 HTTPS 執行應用程式。這些憑證應以 sslcert/cert.pem 和 sslcert/key.pem 的形式儲存在存放區根資料夾。您可能需要將這些金鑰新增至 OS 金鑰鏈結，以便瀏覽器接受。

請確保 *.pem 位於 .gitignore 檔案中，因為您不想將檔案提交至 Git。

啟動伺服器

您可以使用下列指令執行應用程式，將 step01 替換成您要做為伺服器執行的正確步驟 (例如，針對 01-basic-app 執行 step01，如為 02 登入則使用 step02)。

npm run step01

或

npm run step02

這會在 https://localhost:5000 啟動網路伺服器。

你可以在終端機中使用 Control + C 終止伺服器。

Java

設定伺服器

如要透過 HTTPS 執行伺服器，您必須建立自我憑證，用於透過 HTTPS 執行應用程式。

考慮使用 mkcert 進行本機開發。安裝 mkcert 後，下列指令會產生本機儲存的憑證，並透過 HTTPS 執行。

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

這個範例包括資源目錄中的 KeyStore 檔案。您可以視需要儲存檔案，但務必使用相應路徑更新 application.properties 檔案。網域名稱是執行專案的網域 (例如 localhost)。

請確保 *.p12 位於 .gitignore 檔案中，因為您不想將檔案提交至 Git。

啟動伺服器

在 Application.java 檔案中執行 main 方法，以啟動伺服器。舉例來說，在 IntelliJ 中，您可以在 src/main/java/com/addons/spring 目錄中的 Application.java > Run 'Application' 按一下滑鼠右鍵，或是開啟 Application.java 檔案，按一下 main(String[] args) 方法簽名左側的綠色箭頭。或者，您也可以在終端機視窗中執行專案：

./mvnw spring-boot:run

或在 Windows 中執行下列指令：

mvnw.cmd spring-boot:run

這會在 https://localhost:5000 或您在 application.properties 中指定的通訊埠啟動伺服器。