本系列的逐步操作說明,提供有效 Classroom 外掛程式的所有移動部分。每個逐步操作說明都會探討特定概念,並在單一網頁應用程式中實作。目的是協助您設定、設定及啟動功能性外掛程式。
外掛程式必須與 Google Cloud 專案互動。如果您不熟悉 Google Cloud,建議可以參閱入門指南。您可以在 Google Cloud 控制台中管理憑證、API 存取權和 GWM SDK。如要進一步瞭解 GWM SDK,請參閱「Google Workspace Marketplace 清單」指南頁面。
本指南涵蓋下列主題:
- 使用 Google Cloud 建立頁面,以在 Classroom 的 iframe 中顯示。
- 新增 Google 單一登入 (SSO) 功能,並允許使用者登入。
- 發出 API 呼叫,將外掛程式附加到作業中。
- 符合重要的外掛程式提交規定和必要功能。
本指南假設您熟悉程式設計和基本的網頁開發概念。建議您先閱讀專案設定指南,再開始逐步操作說明。本頁提供逐步操作說明中未涵蓋的重要設定詳細資料。
實作範例
JavaScript、Python 與 Java 提供完整的參考範例。這些實作程序是後續頁面中的程式碼範例來源。
下載位置
您可以透過下方連結下載完整的範例封存內容。
必要條件
請詳閱下列各節,準備新的外掛程式專案。
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 憑證頁面。確認您在畫面頂端選取了正確的專案。
- 按一下 [CREATE CREDENTIALS],然後從下拉式選單中選擇「OAuth client ID」(OAuth 用戶端 ID)。
- 在下一頁:
- 將「Application type」(應用程式類型) 設為「Web application」(網頁應用程式)。
- 按一下「授權的重新導向 URI」下方的「新增 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 範例使用快速架構。您可以從上方連結下載完整的原始碼。
本範例需要 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>
子資料夾中找到。每個步驟都包含:
- JavaScript、CSS 和圖片等靜態檔案位於
./<step>/public
資料夾中。 - Express 路由器位於
./<step>/routes
資料夾中。 - 您可在
./<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 的用途)。對於逐步操作說明 2 及之後的逐步操作說明,您也必須包含client_secret.json
檔案的路徑,確保您不會在遠端存放區中加入密鑰。針對逐步操作說明 3 以上版本,應新增 H2 資料庫檔案和檔案資料儲存庫工廠的路徑。關於設定這些資料儲存庫的詳細資訊,請參閱處理重複造訪的第三逐步操作說明。mvnw
和mvnw.cmd
分別是 Unix 和 Windows 的 Maven 包裝函式執行檔。例如,在 Unx 上執行./mvnw --version
會輸出 Apache Maven 版本以及其他資訊。.mvn
目錄包含 Maven 包裝函式的設定。
執行範例伺服器
您必須啟動伺服器才能進行測試。請按照下列操作說明,以您選擇的語言執行範例伺服器:
Python
OAuth 憑證
按照上述說明建立及下載 OAuth 憑證。將 .json
檔案與應用程式的伺服器啟動檔案一起放在根目錄中。
設定伺服器
有多種執行網路伺服器的選項可以選擇。在 Python 檔案結尾,新增下列其中一個選項:
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)
確保
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)
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 金鑰鏈結,瀏覽器才能接受這些金鑰。
您不想將檔案提交至 Git,因此請確保 .gitignore
檔案中有 *.pem
。
啟動伺服器
您可以使用下列指令將 step01
替換成您要做為伺服器執行的正確步驟 (例如將 step01
替換成 01-basic-app,step02
則代表 02 登入)。
npm run step01
或
npm run step02
這會在 https://localhost:3000
啟動網路伺服器。
您可以在終端機中使用 Control + C
終止伺服器。
Java
設定伺服器
如要透過 HTTPS 執行伺服器,您必須建立自行憑證,透過 HTTPS 執行應用程式。
考慮使用 mkcert 進行本機開發作業。安裝 mkcert
後,下列指令會產生儲存在本機的憑證,並透過 HTTPS 執行。
mkcert -install
mkcert -pkcs12 -p12-file <path_to_keystore> <domain_name>
這個範例包含資源目錄中的 KeyStore 檔案。您可以將這個檔案儲存在偏好的任何位置,但請務必使用相應路徑更新 application.properties
檔案。網域名稱就是您執行專案的網域 (例如 localhost
)。
您不想將檔案提交至 Git,因此請確保 .gitignore
檔案中有 *.p12
。
啟動伺服器
在 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
指定的通訊埠啟動伺服器。