本指南简要介绍了构成 Google Classroom API 的主要组件。Google Classroom API 由多个资源和服务组成。资源代表 Google 课堂中的实体，例如课程或作业，而服务会检索和管理这些资源。除了 Google 课堂中存在的属性之外，其中一些实体还具有特定于该 API 的其他属性。主要实体类型包括：
| 实体 | Google 课堂中的表示法 |
|---|---|
| 课程 | 类，例如“M. Smith 的第 4 节数学课程”。 |
| 别名 | 课程的备用 ID。 |
| 邀请 | 向课程添加用户的方式。 |
| 学生 | 课程中的学生。 |
| 教师 | 课程中的教师。 |
| 用户个人资料 | 除学生或教师之外的更通用的用户。 |
| CourseWork | 课程中的作业。 |
| StudentSubmissions | 学生完成指定作业，例如回答或工作表。 |
| CourseWorkMaterials | 面向课程学生的资料。 |
| 通告 | 面向课程中学生的通知。 |
| AddOnAttachment | 作业或资料中的内容或活动，通常显示为嵌入的 iframe。 |
| 主题 | 课程中作业和资料的直观分组。 |
| 注册 | 用于在数据（例如课程名单）发生更改时向应用发送通知的说明。 |
大多数资源都提供用于执行标准操作（例如读取、更新和删除资源实例）的服务方法。某些资源还针对其他操作提供了自定义方法，例如修改分配了特定作业的学生的列表。
如需详细了解 API 资源和方法，请参阅 Google 课堂 API 参考文档。
资源关系概览
- 课程是 Google 课堂中的基础数据对象。
- 别名可用作
Courses的替代标识符。 - 邀请用于邀请用户个人资料成为
Course中的教师或学生，但 Google Workspace 教育版网域管理员也可以直接添加用户。 - 教师可以创建信息流内容，并在其课程中与学生分享。可能的直播内容类型包括课业、课业材料和通知。
CourseWork和CourseWorkMaterials可以直观地整理为主题，并且可以包含插件附件。学生为其CourseWork提交 StudentSubmissions。 - 开发者可以创建注册，以便在其中一些数据发生变化时收到通知。
Google 课堂适用于订阅 Google Workspace 教育版的网域。Google 课堂情境中的网域通常代表一个学区。您可以创建 Google Workspace 教育版测试网域以进行开发，这样您就可以控制 Google 课堂的正式版实例，而不影响真实用户。
课程和别名
Courses 表示类，例如“M. Smith 的第四节数学课程”，以及其指定的教师、学生名单和元数据。每门课程都由服务器分配的唯一 ID 进行标识。Course 资源专门封装了有关课程的所有元数据，例如名称、说明、位置和时间。课程名单通过 Student、Teacher 和 Invitation 资源及其方法进行管理。
Aliases 是课程的替代标识符，可能与课程相关联，并可用来替代唯一 ID。每个别名都存在于一个命名空间中，该命名空间会限制哪些人可以创建和查看该别名。支持以下两个命名空间：
- 网域：网域命名空间非常适合创建所有用户都需要访问但不特定于任何一个程序的别名。例如，课程的其他列表（例如 MATH 127 和 COMSCI 127）应在网域命名空间中创建。只有网域管理员可以创建网域命名空间中的别名，但网域中的所有用户都可以看到这些别名。
- 开发者项目：开发者项目命名空间非常适合管理特定于应用的别名。例如，如果应用使用课程的替代标识符，则可以创建别名，以将其标识符映射到 Google 课堂课程。在此命名空间中创建的别名会与特定的 Google API 控制台相关联。应用的任何用户都可以在该应用的开发者项目的命名空间中创建和查看别名。
如需详细了解如何管理课程元数据和别名，请参阅管理课程。
课程名单和用户
Students 和 Teachers 是用户个人资料与课程之间的特定映射，表示用户在课程中的角色。学生和教师的身份并非全局性质：用户可以在一个课程中被指定为教师，而在另一个课程中被指定为学生。“学生”或“教师”身份代表特定课程中特定用户的一组权限。一门课程可能有多个教师或没有学生。教师和学生可以随时添加到课程中或从课程中移除。
- 学生
Student资源表示以学生身份注册特定课程的用户。学生可以查看课程详细信息和该课程的教师。
- 教师
Teacher资源表示教授特定课程的用户。教师可以查看和更改课程详情、查看教师和学生，以及管理其他教师和学生。
Invitations 及其关联的方法提供了一种便捷的方式来将学生和教师添加到课程。通过创建邀请，用户可以选择是否加入课程，而不是由您通过教师和学生资源直接添加用户。
UserProfiles 表示与用户的网域个人资料的映射，该个人资料由 Directory API 返回的用户唯一 ID 或电子邮件地址标识。当前用户还可以使用 "me" 缩写来引用自己的 ID。
UserProfiles 服务还可用于管理和邀请 Guardians，即学生与监护人之间的映射。Google 课堂中的监护人可以访问学生的部分信息，例如作业。
如需详细了解如何管理名单，请参阅管理教师和学生。
信息流项
动态内容是指与课程成员分享的已发布内容。开发者和教师可以创建三种类型的数据流项：Announcement、CourseWork 和 CourseWorkMaterial。
教师可以在 Google 课堂界面中“信息流”页面顶部创建 Announcements。教师可以点击“课业”标签页中的创建按钮，创建 CourseWork 和 CourseWorkMaterials。开发者可以通过 Google 课堂 API 以编程方式创建所有直播内容类型。
以下是数据流项的特性：
- 所有信息流内容都可以包含补充资料，例如 Google 云端硬盘文件、YouTube 视频、Google 表单、网址超链接和 Google 课堂插件附件。
- 您可以将所有信息流内容分配给课程中的部分学生。
CourseWork可以计分，也可以不计分。教师可以随时更改CourseWork作业的评分状态。- 一个直播内容项可以有多个附件。
- 一个数据流项可以包含不同类型的附件。例如，一个
CourseWork作业可能同时包含 Google 云端硬盘文件、YouTube 视频和 Google 课堂插件附件。 - 一个直播内容项可能包含来自多个开发者的插件附件。
- 开发者可以获取和修改包含其某个插件附件的任何信息流内容资源的详细信息。
- 如果学生提交的
CourseWork作业包含开发者的某个插件附件，开发者可以上交、收回或退回该作业。 - 开发者只能为其创建的作业中的个别学生提交内容最终确定成绩。
已复制的直播内容
教师可以通过复制课程、重复使用作业或将信息流项发布到多门课程来复制信息流项。所有新副本都将具有不同的标识符，如果您要开发 Google 课堂插件，这可能是一个重要考虑因素。请参阅我们关于复制的内容的指南，了解插件如何处理这些情况。
课业和学生提交的作业
CourseWork 项代表课程中一组学生的作业。这是唯一一种可以接受学生提交内容的信息流项类型。CourseWork 资源包含说明、截止日期、最高成绩等详细信息，以及创建时间等元数据。
每个 CourseWork 资源都描述以下某种类型的任务：
- 学生通过提交工作表或其他附件来完成的作业。
- 简答题或单选题。
CourseWork 项的学生作业由 StudentSubmission 表示。它由响应和其他元数据（例如状态和分配的分数）组成。
StudentSubmission 的内容取决于相应 CourseWork 项的类型，并且可能包括：
- 为作业提交的工作表和附件，包括其标题、缩略图和网址，以及可与适当的 API（例如云端硬盘或 YouTube）搭配使用的标识符。
- 简答题或多选题的答案。
如需详细了解如何管理课程作业和学生提交内容，请参阅管理课程作业。
CourseWorkMaterials 和公告
与 CourseWork 类似，CourseWorkMaterials 表示为课程中一组学生分配的内容。每项资源都包含标题、说明等详细信息，以及补充资料。不过，与 CourseWork 不同，CourseWorkMaterials 不需要学生提交任何工件。因此，CourseWorkMaterials 没有截止日期，也不存在 StudentSubmissions。教师可能会使用 CourseWorkMaterials 发布推荐阅读、课程大纲或课堂规则。
Announcements 也表示与一组学生分享的内容，但不包含标题等详细信息，也不能像 CourseWork 或 CourseWorkMaterials 那样按 Topics 进行整理。教师可能会使用这些功能向全班学生发布提醒或通知。
主题
Topics 用于在类中直观地整理 CourseWork 和 CourseWorkMaterials。例如，您可以使用这些属性将作业分组为“可选”和“必做”，或“第 1 单元”和“第 2 单元”。
Google 课堂插件
插件是开发者提供的界面和后端，通常显示在 iframe 中。插件会显示为在线播放内容项上的附件。数据流项可以是任何 Announcements、CourseWork 或 CourseWorkMaterials。插件附件由 AddOnAttachment 表示。
插件附件可以是活动或内容。
- 活动附件要求学生完成并提交单个作业。例如知识问答、抽奖或游戏。您可以选择为活动提交内容评分。
- 内容附件不需要学生提交。学生无需上交附件，并且系统不会对其进行评分。例如照片、文章和视频。
如需了解详情，请参阅插件开发指南。
注册
应用可以在 Google 课堂中发生特定数据更改时订阅通知。例如，在课程的学生名单更新时。Registrations 表示将这些通知发送到应用的指令。
如需了解详情，请参阅推送通知指南。