您的用户是通过 Google Meet 使用 Google 课堂吗?请查看 Apps 脚本快速入门 - 了解如何在 Google Meet 课程中查看学生出席情况

Classroom API 中推送通知

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

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

Google 课堂推送通知概览

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

要接收推送通知,您需要执行以下操作:设置 Cloud Pub/Sub 主题并在创建注册针对相应的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,您可以在网络钩子或轮询订阅端点上接收通知。

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

  1. 确保您满足 Cloud Pub/Sub 前提条件
  2. 设置 Cloud Pub/Sub 客户端
  3. 查看 Cloud Pub/Sub 价格,并为您的 Play 管理中心项目启用结算功能。
  4. 通过开发者控制台创建 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 管理中心项目发出请求的用户将能确定其是否存在,并注册 101}通知。许多应用都将 OAuth 客户端 ID 存储在客户端上,因此最终用户或许可以从您的开发者控制台项目发出请求。如果这适用于您,并且您担心最终用户会向您的 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,这意味着 Rosters 范围或(理想情况)其只读变体(https://www.googleapis.com/auth/classroom.rosters.readonlyhttps://www.googleapis.com/auth/classroom.rosters)。
  • 对于课程作业更改 Feed,这意味着“作业”版本的课程作业范围或(最好)其只读变体(https://www.googleapis.com/auth/classroom.coursework.students.readonlyhttps://www.googleapis.com/auth/classroom.coursework.students)。

如需递送通知,应用必须保留来自授权用户的 OAuth 授权,并授予所需范围。如果用户断开与应用的连接,通知会停止。请注意,目前此网域不支持全网域授权。如果您尝试仅使用全网域授权来注册通知,则会收到“@Missinggrant”错误。

接收通知

通知使用 JSON 进行编码,其中包含:

  • 包含发生更改的资源的集合名称。有关学生名单变动的通知,此字段为 courses.studentscourses.teachers。对于课程作业更改,此属性为 courses.courseWorkcourses.courseWork.studentSubmissions
  • 映射中发生更改的资源的标识符。此映射旨在将参数与相应资源的 get 方法相匹配。对于学生名单变更通知,系统会填充 courseIduserId 字段,并且字段可以不经修改发送到 courses.students.get()courses.teachers.get()。同样,对 courses.courseWork 集合的更改也会包含 courseIdid 字段可以未经修改发送到 courses.courseWork.get(),且对 courses.courseWork.studentSubmissions 集合的更改将具有 courseIdcourseWorkId、和 id 字段,这些字段可未经修改发送到 courses.courseWork.studentSubmissions.get()

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

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

通知还有一个 registrationId 消息特性,该特性包含引发通知的注册标识符,此标识符可用于 registrations.delete()。以取消注册通知。