通过 Classroom API 创建推送通知

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

本文简要介绍了相关概念，并提供了有关如何开始接收推送通知的简单说明。

Google 课堂推送通知概览

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

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

下面列出了本文档中使用的关键概念的定义：

  • 目标位置是指通知的发送位置。
  • Feed 是一种第三方应用可以订阅的通知。例如，“课程 1234 的学生名单更改”。
  • 注册是指向 Google 课堂 API 的指令，用于将特定 Feed 中的通知传送到目标。

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

您的 Cloud Pub/Sub 主题仅会收到与您可以使用创建注册时提供的凭据查看的资源相关的通知。例如，如果用户撤消对您应用的权限或被移除教师身份，系统将不再传送通知。

Feed 类型

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

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

设置 Cloud Pub/Sub 主题

系统会将通知传送到 Cloud Pub/Sub 主题。您可以通过 Cloud Pub/Sub 在 webhook 上接收通知，也可以通过轮询订阅端点接收通知。

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

  1. 确保您满足 Cloud Pub/Sub 前提条件。
  2. 设置 Cloud Pub/Sub 客户端。
  3. 查看 Cloud Pub/Sub 价格，并为您的 Play 管理中心项目启用结算功能。

  4. 您可以在开发者控制台中（最简单）、通过命令行工具（适用于简单的程序化使用）或使用 Cloud Pub/Sub API 创建 Cloud Pub/Sub 主题。请注意，Cloud Pub/Sub 仅允许使用数量有限的主题，因此使用一个主题接收所有通知可确保您的应用在用户众多时不会遇到扩缩问题。

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

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

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

注册应用以接收通知

创建一个 Classroom API 推送通知服务账号可以发布到其中的主题后，您就可以使用 registrations.create() 方法注册接收通知。registrations.create() 方法用于验证推送通知服务账号是否可以访问所提供的 Cloud Pub/Sub 主题。如果推送通知服务账号无法访问主题（例如，主题不存在或您未向其授予相应主题的发布权限），则该方法会失败。

授权

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

  • 对于名单更改 Feed，这意味着“名单”范围或（最好是）其只读变体（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()；对 courses.courseWork.studentSubmissions 集合所做的更改将包含 courseId、courseWorkId 和 id 字段，这些字段可以原封不动地发送到 courses.courseWork.studentSubmissions.get()。

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

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

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