演示

本系列演示文档介绍了正常运行的 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 代码库

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

• Node.js 归档

前提条件

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

HTTPS 证书

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

您可以将 localhost 与 SSL 证书搭配使用；如果您需要针对本地开发创建证书，请考虑使用 mkcert。

Google Cloud 项目

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

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

OAuth 凭据

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

请按照以下步骤创建新的 OAuth 凭据：

• 前往 Google Cloud 凭据页面。确保您已在屏幕顶部选择了正确的项目。
• 点击创建凭据，然后从下拉菜单中选择 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 来处理 build 和管理依赖项。此示例包含 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 目录包含包含 HTML 和 JavaScript 文件的 templates 目录。它还包含 application.properties 文件，该文件指定运行服务器的端口、密钥库文件的路径和 templates 目录的路径。此示例在 resources 目录中包含密钥库文件。您可以将其存储在任何位置，但请务必相应地更新 application.properties 文件的路径。
  • pom.xml 包含构建项目和定义所需依赖项所需的信息。
  • .gitignore 包含不应上传到 Git 的文件名。请务必在此 .gitignore 中添加密钥库的路径。在提供的示例中，此值为 secrets/*.p12（下一部分将介绍密钥库的用途）。对于第 2 步和后续步骤，您还应添加 client_secret.json 文件的路径，以确保您不会在远程代码库中添加密钥。对于第 3 步及之后的演示，您应添加 H2 数据库文件和文件数据存储工厂的路径。如需详细了解如何设置这些数据存储区，请参阅有关处理回访的第 3 个演示文稿。
  • mvnw 和 mvnw.cmd 分别是适用于 Unix 和 Windows 的 Maven 封装容器可执行文件。例如，在 Unix 上运行 ./mvnw --version 会输出 Apache Maven 版本等信息。
  • .mvn 目录包含 Maven 封装容器的配置。

运行示例服务器

要点 ：您的 Web 应用只能通过 HTTPS 在 Google 课堂中打开。如需了解详情，请参阅 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。您可能需要将这些密钥添加到操作系统密钥链中，浏览器才能接受它们。

请确保 *.pem 位于 .gitignore 文件中，因为您不想将该文件提交到 Git。

启动服务器

警告 ：在启动服务器之前，您需要设置 Google Cloud 项目，以访问 Google 课堂 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>

此示例在 resources 目录中包含密钥库文件。您可以将其存储在任何位置，但请务必相应地使用路径更新 application.properties 文件。域名是您运行项目的网域（例如 localhost）。

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

启动服务器

警告 ：在启动服务器之前，您需要设置 Google Cloud 项目，以访问 Google 课堂 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 中指定的端口启动服务器。