本系列逐步操作說明將詳細說明 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 檔案結尾,新增下列其中一項:
未受保護的
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 金鑰鏈結,以便瀏覽器接受。
請確保 *.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
中指定的通訊埠啟動伺服器。