通过 Classroom API 创建推送通知

当 Google 课堂中的数据发生更改时，您可以使用 Registrations 集合中的方法接收通知。

本文提供了概念性概览，以及关于如何开始接收推送通知的简单说明。

Google 课堂推送通知概览

借助 Classroom API 推送通知功能，使用 Classroom API 的应用可以在 Google 课堂中的数据发生更改时订阅通知。 通知通常会在发生更改后的几分钟内发送到 Cloud Pub/Sub 主题。

如需接收推送通知，您需要设置 Cloud Pub/Sub 主题，并在为相应的通知 Feed 创建注册时提供该主题的名称。

以下是本文档中使用的关键概念的定义：

  • 目的地是发送通知的位置。
  • Feed 是一种第三方应用可订阅的通知。例如，“课程 1234 的学生名单有变动”。
  • 注册是 Google 课堂 API 的说明，要求将来自特定 Feed 的通知发送到目标位置。

为 Feed 创建注册后，该注册的 Cloud Pub/Sub 主题会接收来自该 Feed 的通知，直到它到期。您的注册将持续一周，但您可以在注册到期前随时向 registrations.create() 发出相同的请求来延长注册期。

您的 Cloud Pub/Sub 主题只会接收关于您可以使用创建注册时提供的凭据查看的资源的通知。例如，如果用户撤消了应用的权限，或者从教师身份被除名，系统便不会再递送通知。

Feed 类型

Classroom API 目前提供三种类型的 Feed：

  • 每个网域都有一个网域名单变动 Feed，当学生和教师加入和离开该网域中的课程时，会公开相关通知。
  • 每门课程都有一个课程名单变动 Feed，当学生和教师加入和退出该课程中的课程时，系统就会显示通知。
  • 每门课程都有一个课程作业的课程作业更改 Feed，该 API 会在课程中创建或修改任何课程作业或学生提交对象时提供通知。

设置 Cloud Pub/Sub 主题

系统会向 Cloud Pub/Sub 主题发送通知。从 Cloud Pub/Sub 中，您可以通过 Web 钩子或者轮询订阅端点来接收通知。

如需设置 Cloud Pub/Sub 主题，您需要执行以下操作：

  1. 请确保满足 Cloud Pub/Sub 前提条件。
  2. 设置 Cloud Pub/Sub 客户端。
  3. 查看 Cloud Pub/Sub 价格，并为 Developer Console 项目启用结算功能。

  4. 在 Play 管理中心内创建 Cloud Pub/Sub 主题（最简单的方法）、使用命令行工具创建 Cloud Pub/Sub 主题（用于简单的编程用途）或使用 Cloud Pub/Sub API。请注意，Cloud Pub/Sub 仅允许使用有限数量的主题，因此使用一个主题接收所有通知可确保您在应用变得很受欢迎时不会遇到扩缩问题。

  5. 在 Cloud Pub/Sub 中创建订阅，以告知 Cloud Pub/Sub 如何传送您的通知。

  6. 最后，在注册推送通知之前，您需要向推送通知服务帐号授予 (classroom-notifications@system.gserviceaccount.com) 权限以发布到您的主题。

注意：如果您向推送通知服务帐号授予发布到 Cloud Pub/Sub 主题的权限，则能够从您的 Developer Console 项目发出请求的用户将能够确定该主题是否存在，并注册接收该主题的通知。许多应用都将 OAuth 客户端 ID 存储在客户端，因此最终用户或许可以从您的 Developer Console 项目发出请求。如果您属于这种情况，并且担心最终用户向您的 Cloud Pub/Sub 主题发送不必要的通知，或者知道您用于推送通知的 Cloud Pub/Sub 主题的名称，那么您应该考虑从其他 Play 管理中心项目注册推送通知。

注册应用以接收通知

有了 Google 课堂 API 推送通知服务帐号可以发布到的主题后，您可以使用 registrations.create() 方法注册通知。registrations.create() 方法用于验证推送通知服务帐号是否可以访问所提供的 Cloud Pub/Sub 主题。如果推送通知服务帐号无法访问该主题（例如，主题不存在，或者您还没有为该主题授予发布权限），则该方法将失败。

授权

与对 Classroom API 的所有调用一样，对 registrations.create() 的调用必须使用授权令牌进行授权。此身份验证令牌必须包含推送通知范围 (https://www.googleapis.com/auth/classroom.push-notifications) 以及查看所发送通知的相关数据所需的任何范围。

  • 对于名单更改 Feed，这意味着 Roster 范围，或者（理想情况下）其只读变体（https://www.googleapis.com/auth/classroom.rosters.readonly 或 https://www.googleapis.com/auth/classroom.rosters）。
  • 对于课程作业变更 Feed，这意味着课程作业范围的“学生”版本或（理想情况下）其只读变体（https://www.googleapis.com/auth/classroom.coursework.students.readonly 或 https://www.googleapis.com/auth/classroom.coursework.students）。

对于要传送的通知，应用必须保留已获授权的用户授予的具有所需范围的 OAuth 授权。如果用户断开与应用的连接，通知会停止。请注意，全网域授权目前不支持用于此目的。如果您尝试仅使用全网域委派权限注册通知，则会收到 @MissingGrant 错误。

接收通知

通知使用 JSON 编码，包含：

  • 包含发生更改的资源的集合的名称。对于有关名单变更的通知，此字段为 courses.students 或 courses.teachers。对于课程作业变更，此变量为 courses.courseWork 或 courses.courseWork.studentSubmissions。
  • 地图中发生更改的资源的标识符。此映射旨在将参数与相应资源的 get 方法相匹配。对于有关学生名单变更的通知，系统会填充 courseId 和 userId 字段，并且不进行修改即可将其发送到 courses.students.get() 或 courses.teachers.get()。同样，对 courses.courseWork 集合的更改将包括 courseId 和 id 字段，这些字段可以原封不动地发送到 courses.courseWork.get()，id，从而将更改发送到 id但是。courseIdcourseWorkIdcourses.courseWork.studentSubmissions.get()

以下代码段演示了一个示例通知：

{
  "collection": "courses.students",
  "eventType": "CREATED",
  "resourceId": {
    "courseId": "12345",
    "userId": "45678"
  }
}

通知还有一个 registrationId 消息属性，包含导致通知的注册标识符，该标识符可以与 registrations.delete() 配合使用以从通知中取消注册。