简介

同时使用 Google 课堂和第三方工具的教师面临着在多个平台上设置课程和学生名单的难题。这可以通过使用 CSV 上传功能或逐个输入电子邮件地址手动完成。但是，借助 Classroom API，第三方工具可与 API 的最常见用例（学生名单导入）集成，从而减少教师的工作量。

借助学生名单导入功能，第三方平台可以拥有教师或管理员权限，按课程检索课程的元数据、教师和学生。教师可以检索所教授课程的详细信息，而管理员可以访问整个网域内所有课程的详细信息。这种灵活性让开发者能够使用管理员凭据，在单个教师一级或整个网域一级将 Google 课堂名单无缝导入到其平台。

在深入了解名单导入集成的技术细节之前，我们先来查看一个示例工作流程：

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

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

  3. 第三方应用会根据 JSON 响应显示教师的课程名称，以便教师选择课程。应用需要跟踪课程 ID，才能继续执行后续步骤。

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

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

对于工作流中提到的每种方法，您都可以使用 API Explorer 来确切了解每种方法的行为方式。我们还建议您在完成本指南之前先阅读以下内容：

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

汇总了上文详述的学生名单导入工作流的图表。

使用入门

在实现 Google 课堂学生名单导入的具体信息之前，您需要确定需要通过该 API 检索哪些课程和用户信息。您可以在参考文档中查看提供了哪些课程元数据，但其中一些必填字段或常用字段可总结如下：

字段 使用
id 若要检索学生或教师，则必须提供此参数
name 建议采用，以便用户轻松使用，例如在您的网站上显示
ownerId 在域级范围内导入时，此字段为必填字段，用于正确识别课程的主讲教师

系统会在上方工作流的 courses.list 步骤中检索此课程信息。在此请求中，您可以指定特定的请求参数。虽然此方法不需要，但一些建议的参数包括：

参数 使用
courseState 如果未指定，该 API 将返回所有六种 课程状态的课程。我们建议指定 ACTIVE 以检索教师目前正在使用的课程。
pageSize 对于要导入自己课程的教师，我们建议指定较小的 pageSize（小于 10），以缩短 API 调用的响应时间。
pageToken 如果您使用分页请求，则此参数为必填项。
teacherId 推荐原因：网域管理员经常讲授课程。如果未指定，该请求将返回整个网域中教师的课程。
字段 建议缩短 API 调用的响应时间。

现在，您的应用可以使用之前检索到的课程 ID 检索该课程或课程的学生和助理教师列表。此课程 ID 是 teachers.list 和 students.list 的唯一必需查询参数，但您可能同样需要考虑指定 pageSize 和 fields 参数，以缩短 API 调用的响应时间。

如需了解学生和教师资源的所有可用字段，请参阅各自的文档。profile 字段中提供了两个最常用和必需的字段：profile.name 和 profile.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 主题，然后使用 Google 课堂 API 注册该主题。此注册是对 Google 课堂发出的要求，请求将给定 Feed 中的数据发送到给定主题。此 Feed 将成为与教师的 Google 课堂学生名单重新同步的事件触发器。

如需使用推送通知，您需要额外提供一个范围，但无需提交该范围以供验证：

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

汇总了包含推送通知的学生名单导入工作流的图表

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