简介

同时使用 Google 课堂和第三方工具的教师面临着在多个平台上设置课程和学生名单的挑战。他们可能需要手动完成此操作，方法包括上传 CSV 文件或逐个输入电子邮件地址。不过，借助 Google 课堂 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. 使用 Google 课堂 API 管理课程
2. 管理学生和教师

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

使用入门

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

字段	使用
id	检索学生或教师的 API 请求必需
name	建议使用，方便用户使用，例如在您的网站上显示
ownerId	在网域范围内导入时，需要使用此字段来正确标识课程的 主教师

此课程信息是在上述工作流的 courses.list 步骤中检索的。在此请求中，您可以指定某些请求参数。虽然此方法不需要任何参数，但建议使用以下参数：

参数	使用
courseState	如果未指定，API 将返回所有六种 课程状态 的课程。我们建议您指定 ACTIVE 以检索教师当前使用的课程。
pageSize	对于导入自己课程的教师，我们建议指定较小的 pageSize（小于 10），以缩短 API 调用的响应时间。
pageToken	如果您使用的是分页请求，则需要使用此参数。
teacherId	建议使用，因为网域管理员通常会教课程。如果未指定，请求将返回整个网域中教师的课程。
fields	建议使用，以缩短 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
  • 允许您的应用注册任何推送通知活动

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