本系列演示介绍了正常运行的 Google 课堂插件的所有动态部分。每个演示步骤都旨在介绍特定概念,并在单个 Web 应用中实现这些概念。其目标是帮助您设置、配置和发布功能性插件。
您的插件必须与 Google Cloud 项目交互。如果您不熟悉 Google Cloud,建议您阅读入门指南。您可以在 Google Cloud 控制台中管理凭据、API 访问权限和 GWM SDK。如需详细了解 GWM SDK,请访问 Google Workspace Marketplace 产品详情指南页面。
本指南涵盖了以下主题:
- 使用 Google Cloud 创建要在 Google 课堂的 iframe 中显示的页面。
- 添加 Google 单点登录 (SSO) 并允许用户登录。
- 进行 API 调用以将插件附加到作业中。
- 满足关键的插件提交要求和必需的功能。
本指南假定您熟悉编程和基本 Web 开发概念。我们强烈建议您在开始演示之前,先阅读项目配置指南。本页面包含演示未完全涵盖的重要配置详细信息。
实现示例
完整的参考示例提供 JavaScript、Python 和 Java 版本。这些实现是后续页面中所提供示例代码的来源。
下载位置
如需下载示例的完整归档,请点击以下链接。
前提条件
请查看以下部分,准备新的插件项目。
HTTPS 证书
虽然您可以在任何开发环境中托管应用,但“课堂”插件只能通过 https://
使用。因此,您需要一个采用 SSL 加密的服务器来部署应用或在插件 iframe 中进行测试。
可以将 localhost
与 SSL 证书搭配使用;如果您需要为本地开发创建证书,请考虑使用 mkcert。
Google Cloud 项目
您需要配置一个 Google Cloud 项目,以便与这些示例搭配使用。请参阅 Google Cloud 项目创建指南,简要了解开始使用的必要步骤。在第一个演示中,设置 Google Cloud 项目部分还会逐步介绍要执行的特定配置操作。
完成后,将您的 OAuth 2.0 客户端 ID 下载为 JSON 文件;您需要将此凭据文件添加到解压缩的示例目录中。如需了解特定位置,请参阅了解文件。
OAuth 凭据
要创建新的 OAuth 凭据,请按以下步骤操作:
- 前往 Google Cloud Credentials 页面。请确保您在屏幕顶部选择了正确的项目。
- 点击创建凭据,然后从下拉列表中选择 OAuth 客户端 ID。
- 在下一页中:
- 将应用类型设置为 Web 应用。
- 在已获授权的重定向 URI 下,点击添加 URI。为您的应用的回调路由添加完整路径。例如,
https://my.domain.com/auth-callback
或https://localhost:5000/callback
。您将在本演示的后面部分创建并处理此路由。您可以随时修改或添加更多此类路线。 - 点击创建。
- 然后,您会收到一个包含新建凭据的对话框。选择下载 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/
。这些数字对应于具体的演示步骤。每个目录都包含一个功能齐全的 Web 应用,该应用可实现特定演示中所述的功能。例如,/01-basic-app/
目录包含创建插件演示的最终实现。
目录内容
目录内容因实现语言而异:
Python
目录根目录包含以下文件:
main.py
- Python 应用入口点。指定要在此文件中使用的服务器配置,然后运行它以启动服务器。requirements.txt
- 运行 Web 应用所需的 Python 模块。可以使用pip install -r requirements.txt
自动安装这些模块。client_secret.json
- 从 Google Cloud 下载的客户端密钥文件。请注意,这未包含在示例归档文件中;您应该重命名下载的凭据文件并将其复制到每个目录的根目录中。
config.py
- Flask 服务器的配置选项。webapp
目录包含 Web 应用的内容。此软件包包含以下工具:/templates/
目录,其中包含用于各种页面的 Jinja 模板。/static/
目录,其中包含图片、CSS 和辅助 JavaScript 文件。routes.py
- Web 应用路由的处理程序方法。__init__.py
-webapp
模块的初始化程序。此初始化程序会启动 Flask 服务器并加载config.py
中设置的配置选项。特定演示步骤所需的其他文件。
Node.js
演示的每一步都可在其各自的 <step>
子文件夹中找到。每个步骤均包含:
- JavaScript、CSS 和图片等静态文件位于
./<step>/public
文件夹中。 - Express 路由器位于
./<step>/routes
文件夹中。 - HTML 模板位于
./<step>/views
文件夹中。 - 服务器应用为
./<step>/app.js
。
Java
项目目录包含以下内容:
src.main
目录包含成功运行应用所需的源代码和配置。此目录包含以下内容: +java.com.addons.spring
目录包含Application.java
和Controller.java
文件。Application.java
文件负责运行应用服务器,而Controller.java
文件负责处理端点逻辑。 +resources
目录包含带有 HTML 和 JavaScript 文件的templates
目录。它还包含application.properties
文件,用于指定运行服务器的端口、密钥库文件的路径以及templates
目录的路径。此示例将密钥库文件放在resources
目录中。您可以视需要将其存储在任何位置,但请务必使用相应的路径更新application.properties
文件。pom.xml
包含构建项目和定义所需依赖项所需的信息。.gitignore
包含不应上传到 git 的文件名。请务必在此.gitignore
中添加密钥库的路径。在所提供的示例中,其为secrets/*.p12
(密钥库的用途将在下一节中讨论)。对于演示 2 及之后的演示,您还应添加client_secret.json
文件的路径,以确保不在远程代码库中包含您的 Secret。对于演示 3 及更高版本,您应添加 H2 数据库文件和文件数据存储区工厂的路径。如需详细了解如何设置这些数据存储区,请参阅关于处理重复访问的第三个演示。mvnw
和mvnw.cmd
分别是适用于 Unix 和 Windows 的 Maven 封装容器可执行文件。例如,在 Unix 上运行./mvnw --version
会输出 Apache Maven 版本及其他信息。.mvn
目录包含 Maven 封装容器的配置。
运行示例服务器
您需要启动服务器才能进行测试。请按照以下说明以您选择的语言运行示例服务器:
Python
OAuth 凭据
如上所述创建和下载您的 OAuth 凭据。将 .json
文件放在应用的服务器启动文件旁边。
配置服务器
您可以通过多种方式运行 Web 服务器。在 Python 文件的末尾,添加以下内容之一:
localhost
不安全。请注意,这仅适用于直接在浏览器窗口中进行测试;无法在 Google 课堂插件 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
点击显示的网址,在浏览器中查看您的 Web 应用,确认其运行正常。
Node.js
配置服务器
为了通过 HTTPS 运行服务器,您需要创建一个用于通过 HTTPS 运行应用的自证书。这些凭据应保存为 sslcert/cert.pem
和 sslcert/key.pem
,并保存在代码库根文件夹中。您可能需要将这些密钥添加到操作系统密钥链中,才能让浏览器接受它们。
确保您的 .gitignore
文件中包含 *.pem
,因为您不想将文件提交到 git。
启动服务器
您可以使用以下命令运行应用,并将 step01
替换为您要作为服务器运行的正确步骤(例如,step01
代表 01-basic-app,step02
代表 02-sign-in)。
npm run step01
或
npm run step02
这将在 https://localhost:5000
启动 Web 服务器。
您可以在终端中使用 Control + C
终止服务器。
Java
配置服务器
为了通过 HTTPS 运行服务器,您需要创建一个用于通过 HTTPS 运行应用的自证书。
请考虑使用 mkcert 进行本地开发。
安装 mkcert
后,以下命令会生成本地存储的证书,以便通过 HTTPS 运行。
mkcert -install
mkcert -pkcs12 -p12-file <path_to_keystore> <domain_name>
此示例将密钥库文件放在资源目录中。您可以视需要将其存储在任何位置,但请务必使用相应的路径更新 application.properties
文件。该域名是您运行项目的网域(例如 localhost
)。
确保您的 .gitignore
文件中包含 *.p12
,因为您不想将文件提交到 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
中指定的端口启动服务器。