Google 课堂插件现已面向开发者正式推出！如需了解详情，请参阅插件文档。

通过 Classroom API 创建推送通知

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

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

课堂推送通知概览

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

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

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

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

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

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

Feed 类型

课堂 API 提供三种类型的 Feed：

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

设置 Cloud Pub/Sub 主题

通知会发送到 Cloud Pub/Sub 主题。您可以通过 Webhook 或轮询订阅端点从 Cloud Pub/Sub 接收通知。

如需设置 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) 授予向您的主题发布内容的权限。

为您的应用注册通知

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

授权

与对课堂 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() 结合使用，以取消注册通知。