演示

本系列演示介绍了正常运行的 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 文件的末尾，添加以下内容之一：

  1. 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)

  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

点击显示的网址，在浏览器中查看您的 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:3000 启动 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 中指定的端口启动服务器。