简介

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

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

网域管理员可能会像自有课程的教师一样使用第三方工具。通过 API 检索课程详细信息时，需要仔细处理网域管理员权限与教师权限之间的差异。

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

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

2. 第三方应用通过 Classroom 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 的实时示例，以便更好地了解此类集成。

使用入门

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

字段	使用
id	对于检索学生或教师的 API 请求，此参数是必需的
name	建议使用，以便于用户使用（即在您的网站上显示）
ownerId	在网域范围内导入时需要此字段，以便正确识别课程的主教师

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

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

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

如需查看 student 和 teacher 资源的所有可用字段，请参阅各自的文档。最常用的两个字段（通常是必需字段）位于 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 主题，然后向 Classroom API 注册该主题。此注册请求旨在让 Google 课堂将指定 Feed 中的数据发送到指定主题。此 Feed 将作为与教师的 Google 课堂名册重新同步的事件触发器。

您可以按课程或网域订阅通知，具体取决于应用的用例。

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

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

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