简介

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

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

网域管理员在教授自己的课程时可能会使用第三方工具。通过 API 检索课程详情时，需要谨慎处理网域管理员权限和教师权限之间的差异。

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

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. 管理学生和教师

除了下面的工作流程图之外，您还可以查看 ActivelyLearn 的实例，以便更好地了解此类集成。

使用入门

在实现 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
  • 对教师和学生的电子邮件属性提供读取权限

由于其中一个范围被视为敏感范围，因此您的应用需要完成验证流程。

使用 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 课堂推送通知集成，请参阅我们的管理推送通知指南。