将链接附件升级为 Google 课堂插件附件

教师向 Google 课堂添加第三方内容的方法之一是： 将链接作为链接附件粘贴到作业创建页面中。构建 你现在可以将插件配置为 允许教师将链接附件升级为插件附件。

概览

如果您为插件配置此功能，系统会提示教师 将链接附件粘贴到 创建作业的页面。只有在教师已设置权限时，系统才会提示他们执行此操作 您是否已安装该插件。

教师同意将链接升级为插件附件后，链接 升级 iframe 时包含以下查询参数：

• courseId
• itemId
• itemType
• addOnToken
• urlToUpgrade
• login_hint（仅当用户已向您的应用授权时）

前四个查询参数反映的是 附件发现 iframe。urlToUpgrade 查询参数是新的， 可帮助您评估应如何创建插件附件。然后，您可以使用 检查用户是否已登录，然后调用 CreateAddOnAttachment courseWork、courseWorkMaterials 或 announcements（基于 itemType 值）。在 iframe 中，您可以 显示一个加载屏幕，告知教师 正在创建。

创建插件附件后，系统将关闭 iframe， 教师可以照常查看作业中的附件。

技术实现详情

本部分重点介绍了此功能的一些重要技术细节。

读取 urlToUpgrade 查询参数

urlToUpgrade 查询参数在通过 Link 传递时采用 URI 编码 升级 iframe。您必须对网址进行解码，以获取原始形式的网址。如果 使用 JavaScript，则可以使用 decodeURIComponent() 函数。

关闭链接升级 iframe

为确保此功能提供最佳用户体验，请发送一次 postMessage 已成功创建插件附件。此操作将关闭 iframe。请参阅 iframe 实现详情页面，了解更多详情。

配置详情

要将此功能集成到您的 插件：

• 链接升级 iframe 的网址：此网址会在 iframe。

• Google 课堂应检测并尝试识别的网址格式 升级：网址格式可以由一个主机和多个路径组成 前缀。

  • 您可以提供多个网址格式。
  • 如果未提供任何路径前缀，则使用与主机匹配的任何网址 可以升级
  • 只有采用 https 架构的网址才能升级。
  • 网址格式不得包含 localhost。
  • 路径前缀不得包含查询参数或网址片段。
  • 路径前缀目前不支持通配符，但主机不可以：
    • example.com 是有效主机， 和 /foo 和 /bar/*/baz 是有效的路径前缀。
    • “example.*.host.com”不是 有效主机。
  • 路径前缀组成部分之间的通配符仅与单个 并且不与以正斜线分隔的多个组件匹配。 假设网址格式包含主机 example.com 和路径前缀 /bar/*/baz：
    • https://example.com/bar/123/baz 是该网址的有效匹配项 模式。
    • https://example.com/bar/123/baz/456/789是 网址格式。
    • https://example.com/bar/123/456/baz不是有效的 网址格式，因为路径前缀中的通配符不匹配 /123/456/。

。

注意： 路径前缀组成部分之间的通配符仅与单个组成部分匹配。

开发流程

发送用于测试或正式版的链接升级 iframe 网址和网址格式 请发送电子邮件至 [e-mail]。

您可以为代表 课堂插件。我们建议您首先提供 配置公开透明的插件 并在演示网域中进行测试，而不会影响实际用户。

配置完成后，您会通过电子邮件收到回复 。请注意，此 API 不支持使用 localhost 的网址格式 功能。

重要提示： 如果用户可以安装和使用您的插件，可以将链接升级到 插件启用这些配置后， Google 课堂团队敬上因此，必须先提供 在测试或开发环境中测试插件的 配置 提供任何生产环境配置。

设置电子邮件的格式，使其包含以下内容：

Google Cloud Project number: GCP_PROJECT_NUMBER

Link Upgrade iframe URL: LINK_UPGRADE_IFRAME_URL

URL Patterns:
-   Host:HOST_1
-   Path prefixes:
  -   PATH_PREFIX_1
  -   PATH_PREFIX_2

-   Host:HOST_2
-   Path prefixes:
  -   PATH_PREFIX_3
  -   PATH_PREFIX_4

// add more hosts and path prefixes as needed

替换以下内容：

• GCP_PROJECT_NUMBER：Google Cloud 项目的编号 以及该插件所关联的内容
• LINK_UPGRADE_IFRAME_URL：应在 链接升级 iframe。
• HOST_1：Google 课堂应检测到的主机。只有 支持 https 架构。
• PATH_PREFIX_1 和 PATH_PREFIX_2：路径 Google 课堂应检测并尝试与 HOST_1 关联的前缀 以进行升级。
• HOST_2：Google 课堂应检测到的主机。只有 支持 https 架构。
• PATH_PREFIX_3 和 PATH_PREFIX_4：路径 Google 课堂应检测并尝试与 HOST_2 关联的前缀 以进行升级。

建议的用户体验

以下是实现此功能时要考虑的一些建议。

避免教师额外工作

如果您遇到以下情况，强烈建议您使用 iframe 以方便登录 或显示加载指示器。为了提供最佳用户体验， 完成相应任务后， 同意将粘贴的链接升级为插件附件。但是，如果 但您的插件无法实现，您可以使用“链接升级” iframe 收集 提供所需的额外信息iframe 还可用于通知 如果无法升级链接或出现错误，则会联系教师。

包含方便用户使用的访问错误消息

如果教师粘贴并升级他们无权访问的链接，系统会显示 提供便于用户理解的错误消息，以便教师了解相应问题。 iframe 还可用于向教师提供适当的 访问相应内容的权限。