逐步操作說明

這一系列的操作說明會示範 Classroom 外掛程式的所有運作元件。每個逐步操作步驟都會說明特定概念，並在單一網頁應用程式中實作這些概念。目的是協助您設定、配置及啟動功能性外掛程式。

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

本指南涵蓋下列主題：

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

本指南假設您已熟悉程式設計和網路開發的基本概念。強烈建議您在開始操作前，先閱讀專案設定指南。本頁面包含逐步操作說明中未完全涵蓋的重要設定詳細資料。

實作範例

您可以在 Python 中找到完整的參考範例。部分實作項目也可在 Java 和 Node.js 中使用。這些實作內容是後續頁面中範例程式碼的來源。

下載位置

Python 和 Java 範例可在 GitHub 存放區中找到：

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

必要條件

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

HTTPS 憑證

雖然您可以在任何開發環境中代管應用程式，但 Classroom 外掛程式只能透過 https:// 使用。因此，您需要使用支援 SSL 加密的伺服器，才能部署應用程式或在外掛程式 iframe 中測試應用程式。

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

Google Cloud 專案

您必須設定 Google Cloud 專案，才能搭配這些範例使用。請參閱 Google Cloud 專案建立指南，瞭解開始使用所需的步驟。第一個逐步操作說明中的「設定 Google Cloud 專案」一節，也會逐步說明應採取的特定設定動作。

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

OAuth 憑證

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

  • 前往 Google Cloud 憑證頁面。請確認您已選取畫面頂端的正確專案。
  • 按一下「建立憑證」，然後從下拉式選單中選擇「OAuth 用戶端 ID」。
  • 在下一個頁面中：
    • 將「應用程式類型」設為「網頁應用程式」。
    • 按一下「Authorized redirect URIs」下方的「ADD URI」。為應用程式回呼路徑新增完整路徑。例如 https://my.domain.com/auth-callback 或 https://localhost:5000/callback。您會在本逐步操作說明的後續部分建立及處理這個路徑。您隨時可以編輯或新增更多這類路線。
    • 點選「建立」。
  • 接著，您會收到對話方塊，其中包含新建立的憑證。選擇「Download 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 16.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 範本。

  • /static/ 目錄，其中包含圖片、CSS 和輔助 JavaScript 檔案。

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

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

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

Node.js

每個逐步操作步驟都會放在專屬的 <step> 子資料夾中。每個步驟都包含：

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

Java

專案目錄包含下列項目：

  • src.main 目錄包含成功執行應用程式所需的原始碼和設定。這個目錄包含下列項目： + java.com.addons.spring 目錄包含 Application.java 和 Controller.java 檔案。Application.java 檔案負責執行應用程式伺服器，而 Controller.java 檔案則負責處理端點邏輯。+ resources 目錄包含 templates 目錄，其中含有 HTML 和 JavaScript 檔案。它還包含 application.properties 檔案，可用於指定執行伺服器的連接埠、金鑰庫檔案的路徑，以及 templates 目錄的路徑。此範例會納入 resources 目錄中的金鑰庫檔案。您可以將其儲存在任何偏好的位置，但請務必根據路徑更新 application.properties 檔案。
    • pom.xml 包含建構專案所需的資訊，並定義必要的依附元件。
    • .gitignore 包含不應上傳至 Git 的檔案名稱。請務必在這個 .gitignore 中新增 KeyStore 路徑。在提供的範例中，這個值為 secrets/*.p12 (下節會討論鍵值儲存庫的用途)。在第 2 個操作說明和之後的操作說明中，您也應加入 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-sign-in 為 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 中指定的通訊埠啟動伺服器。