简介

同时使用 Google 课堂和第三方工具的教师面临着跨多个平台设置课程和学生名单的挑战。此操作可通过手动完成,方法包括使用 CSV 上传或逐个输入电子邮件地址。但是,借助 Classroom API,第三方工具可以通过集成该 API 最常见的用例学生名单导入来减少教师的工作负载。

借助学生名单导入功能,第三方平台可以使用教师或管理员权限按课程检索课程的元数据、教师和学生。教师可以检索所讲课程的详细信息,而管理员可以访问整个网域中的所有课程的详细信息。借助这种灵活性,开发者可以在个人教师级别或整个网域中使用管理员凭据无缝地将 Google 课堂学生名单加入他们的平台。

在深入了解有关名单导入集成的技术细节之前,我们先来看一个示例工作流:

  1. 在第三方应用中,教师可以选择导入 Google 课堂课程的选项。

  2. 第三方应用通过 Room API 调用 courses.list 方法,该方法会返回包含教师所有课程的响应 JSON。

  3. 在 json 响应中,第三方应用会显示教师的课程标题,以供教师选择。应用需要跟踪课程 ID 才能继续执行下一步骤。

  4. 第三方应用使用所选的课程 ID 调用 students.listteachers.list 方法,并在其网站上显示所有名称,以供教师确认导入。

  5. 第三方应用使用 students.listteachers.list 响应 JSON 中返回的电子邮件地址邀请用户加入其平台上新导入的课程。

对于工作流中提到的每种方法,您可以使用 API Explorer 了解每种方法的确切行为方式。此外,我们还建议您在完成本指南之前完成以下预读材料:

  1. 使用 Classroom API 管理课程
  2. 管理学生和教师

该示意图总结了上文详述的学生名单导入工作流程。

入门指南

在实施 Google 课堂学生名单导入的具体细节之前,您需要确定需要通过 API 检索哪些课程和用户信息。您可以在参考文档中查看有哪些课程元数据,但所需的一些必填字段或通用字段总结如下:

字段 使用
id 如果使用 API 请求检索学生或教师,则必须使用此参数
name 建议以便于用户使用,即在您的网站上展示
ownerId 在全网域导入时需要启用,以便正确识别课程的主讲教师

本课程信息在上述工作流的 courses.list 步骤中检索。在此请求中,您可以指定某些请求参数。虽然此方法不需要任何参数,但推荐的参数包括:

参数 使用
courseState 如果未指定,API 将返回全部六个 课程状态的课程。我们建议指定 ACTIVE 以检索教师当前使用的课程。
pageSize 对于要导入自己的课程的教师,我们建议指定较小的 pageSize(少于 10),以缩短 API 调用的响应时间。
pageToken 如果您使用的是分页请求,则为必需。
teacherId 推荐原因:网域管理员经常教授课程。如果不指定,请求会返回整个网域中的教师的课程。
字段 建议缩短 API 调用的响应时间。

现在,您的应用可以使用之前检索到的课程 ID 检索相应课程的学生和助理教师列表。本课程 ID 是 teachers.liststudents.list 的唯一必需查询参数,但您可能也需要考虑指定 pageSizefields 参数,以缩短 API 调用的响应时间。

学生教师资源的所有可用字段可在各自的文档中找到。profile 字段中提供了两个最常用且通常必需的字段:profile.nameprofile.emailAddress

字段 使用
profile.name 建议以便于用户使用,即在您的网站上展示
profile.emailAddress 如果应用希望对学生进行唯一标识,则必须提供

如需检索和使用 Google 课堂中的任何课程或学生名单详细信息,您的应用需要向用户请求授权。实现此工作流需要用到三 (3) 个范围:

  • https://www.googleapis.com/auth/classroom.courses.readonly
    • 提供对 Google 课堂课程的只读权限
  • https://www.googleapis.com/auth/classroom.rosters.readonly
    • 提供对 Google 课堂课程学生名单的只读权限(教师和学生)
  • https://www.googleapis.com/auth/classroom.profile.emails
    • 提供对教师和学生的 email 属性的读取权限

将名单与 Pub/Sub 通知同步

随着学年的进行,学生名单可能会随着学生流失或课程添加而发生变化。通过添加 Pub/Sub 通知,您可以使第三方应用与 Google 课堂的学生名单保持同步。如需接收通知,请设置 Google Cloud Pub/Sub 主题,然后使用 Classroom API 注册该主题。此注册是对 Google 课堂发出的数据请求,要求将给定 Feed 中的数据发送到指定主题。此 Feed 将成为与教师的 Google 课堂学生名单重新同步的事件触发器。

使用推送通知需要一个额外的作用域,无需提交以进行验证:

  • https://www.googleapis.com/auth/classroom.push-notifications
    • 允许您的应用注册所有推送通知 Activity

该示意图汇总了使用推送通知的学生名单导入工作流

如需详细了解如何与 Google 课堂推送通知集成,请参阅我们的管理推送通知指南