演示

本系列演示介绍了一个有效的 Google 课堂插件的所有移动部分。每个演示步骤都针对特定概念，在单个 Web 应用中实现它们。目的是帮助您设置、配置和发布一个功能性插件。

您的插件必须与 Google Cloud 项目交互。如果您不熟悉 Google Cloud，建议您阅读入门指南。您可以在 Google Cloud 控制台中管理凭据、API 访问权限和 Google Workspace Marketplace SDK。如需详细了解 Marketplace SDK，请访问 Google Workspace Marketplace 产品信息指南页面。

本指南涵盖了以下主题：

• 使用 Google Cloud 创建要在 Google 课堂的 iframe 中显示的页面。
• 添加 Google 单点登录 (SSO) 并允许用户登录。
• 进行 API 调用以将插件附加到作业中。
• 满足关键的插件提交要求和所需的功能。

本指南假定您熟悉编程和基本的 Web 开发概念。我们强烈建议您在开始演示之前阅读项目配置指南。本页面包含演示中未完整涵盖的重要配置详细信息。

实现示例

完整的参考示例可在 Python 中找到。Java 和 Node.js 也提供了部分实现。这些实现是后续页面中的示例代码的来源。

下载位置

GitHub 代码库中提供了 Python 和 Java 示例：

• Python 代码库

• Java 代码库

您可以下载 zip 文件的 Node.js 示例：

• Node.js 归档

前提条件

请查看以下部分以准备新的插件项目。

HTTPS 证书

虽然您可以在任何开发环境中托管应用，但 Google 课堂插件只能通过 https:// 使用。因此，您需要一台采用 SSL 加密的服务器来部署应用或在插件 iframe 中进行测试。

您可以在 SSL 证书中使用 localhost；如果您需要创建用于本地开发的证书，请考虑使用 mkcert。

Google Cloud 项目

您需要配置一个 Google Cloud 项目，以便与这些示例搭配使用。如需简要了解开始使用所需的步骤，请参阅 Google Cloud 项目创建指南。第一个演示中的设置 Google Cloud 项目部分还逐步介绍了要执行的特定配置操作。

完成后，以 JSON 文件格式下载 OAuth 2.0 客户端 ID；您需要将此凭据文件添加到解压缩的示例目录中。如需查看特定位置，请参阅了解文件。

OAuth 凭据

要点 ：您的 Web 应用必须使用在 Google Cloud 中管理的 OAuth 2.0 凭据。

要创建新的 OAuth 凭据，请按以下步骤操作：

• 前往 Google Cloud 凭据页面。请确保您在屏幕顶部选择了正确的项目。
• 点击创建凭据，然后从下拉列表中选择 OAuth 客户端 ID。
• 在下一页上：
  • 将应用类型设置为网页应用。
  • 在已获授权的重定向 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 下载的客户端密钥文件。请注意，示例归档文件中不包含该文件；您应该重命名下载的凭据文件并将其复制到每个目录根目录中。

    重要提示 ：您必须先提供 Google Cloud 项目中的客户端密钥文件，然后才能运行示例。

• config.py - Flask 服务器的配置选项。

• webapp 目录包含 Web 应用的内容。此软件包包含以下工具：

• /templates/ 目录，其中包含适用于各种页面的 Jinja 模板。

• 包含图片、CSS 和辅助 JavaScript 文件的 /static/ 目录。

• routes.py - Web 应用路由的处理程序方法。

• __init__.py - webapp 模块的初始化程序。此初始化程序会启动 Flask 服务器并加载 config.py 中设置的配置选项。

• 特定演示步骤所需的其他文件。

Node.js

演示的每个步骤都可以在其各自的 <step> 子文件夹中找到。每个步骤都包含：

• JavaScript、CSS 和图片等静态文件位于 ./<step>/public 文件夹中。
• 快速路由器位于 ./<step>/routes 文件夹中。
• 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 中添加密钥库的路径。在提供的示例中，这是 secrets/*.p12（我们将在下面的部分中讨论密钥库的用途）。对于演示 2 及后续演示，您还应添加 client_secret.json 文件的路径，以确保不在远程仓库中包含您的 Secret。对于演示 3 及更高版本，您应添加 H2 数据库文件和文件数据存储区工厂的路径。如需详细了解如何设置这些数据存储区，请参阅有关处理重复访问的第三步演示。
  • mvnw 和 mvnw.cmd 分别是适用于 Unix 和 Windows 的 Maven 封装容器可执行文件。例如，在 Unix 上运行 ./mvnw --version 会输出 Apache Maven 版本以及其他信息。
  • .mvn 目录包含 Maven 封装容器的配置。

运行示例服务器

要点 ：只能通过 HTTPS 在 Google 课堂中打开您的 Web 应用。如需了解更多详情，请参阅 HTTPS 证书部分。

您需要启动服务器才能对其进行测试。请按照以下说明使用您选择的语言运行示例服务器：

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")
   

启动服务器

警告 ：在启动服务器之前，您需要设置 Google Cloud 项目以访问 Classroom API 和所需的凭据。

按照上一步中的配置，运行 Python 应用以启动服务器。

python main.py

点击显示的网址，在浏览器中查看您的 Web 应用，确认其运行正常。

Node.js

配置服务器

为了通过 HTTPS 运行服务器，您需要创建一个用于通过 HTTPS 运行应用的自证书。这些凭据应以 sslcert/cert.pem 和 sslcert/key.pem 的形式保存在代码库根文件夹中。您可能需要将这些密钥添加到操作系统密钥链中，浏览器才能接受它们。

确保您的 .gitignore 文件中包含 *.pem，因为您不想将文件提交到 git。

启动服务器

警告 ：在启动服务器之前，您需要设置 Google Cloud 项目以访问 Classroom API 和所需的凭据。

您可以使用以下命令运行应用，并将 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。

启动服务器

警告 ：在启动服务器之前，您需要设置 Google Cloud 项目以访问 Classroom API 和所需的凭据。

通过运行 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 中指定的端口启动服务器。