通过 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，当该课程中创建或修改任何课程作业或学生提交对象时，系统会显示通知。

设置 Cloud Pub/Sub 主题

系统会将通知传送到 Cloud Pub/Sub 主题。在 Cloud Pub/Sub 中 通过 Web hook 或通过轮询订阅端点来接收通知。

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

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

  4. 在 Developer Console 中创建 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 主题发布消息的权限，那么能够从您的 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(). 同样，对 courseWork 集合所做的更改 无需修改即可发送到的 courseId 和 id 字段 courses.courseWork.get() 对 courseWork.studentSubmissions 集合的更改 包含 courseId、courseWorkId 和 id 字段，这些字段无需修改即可发送 更改为 courses.courseWork.studentSubmissions.get().

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

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

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