通过 Classroom API 创建推送通知

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

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

Google 课堂推送通知概览

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

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

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

目的地是指通知的发送位置。
Feed 是一种第三方应用可以订阅的通知。例如，“课程 1234 的学生名单变更”。
注册是指指示 Classroom API 将特定 Feed 中的通知传递到目标位置。

为 Feed 创建注册后，相应注册的 Cloud Pub/Sub 主题会接收来自该 Feed 的通知，直到注册过期。您的注册有效期为一周，但您可以在有效期结束前的任何时间通过向 registrations.create() 提交相同的请求来延长有效期。

您的 Cloud Pub/Sub 主题只会接收有关您在创建注册时提供的凭据可查看的资源的通知。例如，如果用户撤消了对您的应用的权限，或者被移除教师身份，则系统将不再发送通知。

Feed 类型

Classroom API 提供三种类型的 Feed：

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

设置 Cloud Pub/Sub 主题

通知会传递到 Cloud Pub/Sub 主题。通过 Cloud Pub/Sub，您可以通过 webhook 或轮询订阅端点来接收通知。

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

确保您满足 Cloud Pub/Sub 前提条件。
设置 Cloud Pub/Sub 客户端。
查看 Cloud Pub/Sub 定价，并为您的开发者控制台项目启用结算功能。
在开发者控制台中（最简单）、通过命令行工具（用于简单的程序化使用）或使用 Cloud Pub/Sub API 创建 Cloud Pub/Sub 主题。请注意，Cloud Pub/Sub 仅允许有限数量的主题，因此使用一个主题来接收所有通知可确保您的应用在变得热门时不会遇到扩缩问题。
在 Cloud Pub/Sub 中创建订阅，以告知 Cloud Pub/Sub 如何传送通知。
最后，在注册推送通知之前，您需要向推送通知服务账号 (classroom-notifications@system.gserviceaccount.com) 授予向您的主题发布消息的权限。

注册应用以接收通知

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

授权

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

对于花名册更改 Feed，这意味着 Rosters 范围或（理想情况下）其只读变体（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() 结合使用，以取消注册通知。