API 资源

本指南简要介绍了 Google Classroom API 的主要构成组件。Google Classroom API 由多个资源和服务组成。 资源表示 Google 课堂中的实体，例如课程或作业，而服务用于检索和管理这些资源。除了 Classroom 中已有的属性之外，其中一些实体还具有特定于 API 的其他属性。主要实体类型包括：

实体	Google 课堂中的表示法
课程	一种课程，例如“M. Smith 的第四节数学课”。
别名	课程的备用 ID。
邀请	一种将用户添加到课程的方法。
学生	课程中的学生。
教师	课程中的教师。
用户个人资料	更通用的用户，不属于学生或教师。
CourseWork	课程中的作业。
StudentSubmissions	学生针对特定作业提交的作业，例如答案或工作表。
CourseWorkMaterials	课程中学生的资料。
通告	面向课程中学生的通知。
AddOnAttachment	作业或资料中的内容或活动，通常以嵌入式 iframe 的形式显示。
主题	课程中作业和资料的直观分组。
注册	一项指令，用于在数据（例如课程学生名单）发生更改时向您的应用发送通知。

大多数资源都有用于执行标准操作（例如读取、更新和删除资源实例）的服务方法。某些资源还具有用于其他操作的自定义方法，例如修改分配了特定作业的学生名单。

如需详细了解 API 资源和方法，请参阅 Classroom API 参考文档。

资源关系概览

• 课程是 Google 课堂中的基础数据对象。
• 别名用作 Courses 的替代标识符。
• 邀请用于邀请用户个人资料成为 Course 中的教师或学生，但用户也可以由 Google Workspace 教育版网域管理员直接添加。
• 教师可以创建动态内容，并与课程中的学生分享。可能的信息流项类型包括 Coursework、CourseWorkMaterials 和 Announcements。CourseWork 和 CourseWorkMaterials 可以直观地整理为主题，并且可以包含 AddOnAttachments。学生提交 StudentSubmissions 以完成 CourseWork。
• 开发者可以创建注册，以便在部分数据发生更改时收到通知。

Google 课堂适用于订阅 Google Workspace 教育版的网域。在 Google 课堂环境中，网域通常表示学区。您可以创建 Google Workspace 教育版测试网域以进行开发，这样您就可以控制 Classroom 的正式版实例，而不会影响真实用户。

课程和别名

Courses 表示一个类，例如“M. “史密斯老师的四年级数学课”，以及其分配的教师、学生名单和元数据。每门课程都由服务器分配的唯一 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。

教师可以在 Classroom 界面的“信息流”页面顶部创建 Announcements。教师可以在“课业”标签页中点击创建按钮来创建 CourseWork 和 CourseWorkMaterials。 开发者可以通过 Classroom API 以编程方式创建所有类型的信息流项。

以下是有关流媒体项的真实信息：

• 所有动态内容都可以包含补充资料，例如 Google 云端硬盘文件、YouTube 视频、Google 表单、网址超链接和 Classroom 插件附件。
• 您可以将所有信息流内容布置给课程中的部分学生。
• CourseWork 可以评分，也可以不评分。教师可以随时更改CourseWork作业的评分状态。
• 一个动态项目可以有多个附件。
• 动态中的内容项可以包含不同类型的附件。例如，一个CourseWork作业可能同时包含 Google 云端硬盘文件、YouTube 视频和 Google 课堂插件附件。
• 一个信息流项目可能包含来自多个开发者的附加附件。
• 开发者可以获取和修改附加了其插件附件的任何信息流内容资源的详细信息。
• 对于包含其插件附件的 CourseWork 作业，开发者可以上交、回收或发回学生提交的作业。
• 开发者只能最终确定其创建的作业中个别学生提交的内容的成绩。

已复制直播内容

教师可以通过复制课程、重复使用作业或将动态项目发布到多门课程来复制动态项目。任何新副本都将具有不同的标识符，如果您正在开发 Classroom 加购项，这可能是一个重要的考虑因素。请参阅我们关于复制内容的指南，了解插件如何处理这些情况。

CourseWork 和 StudentSubmissions

CourseWork 项表示课程中一组学生的作业。这是唯一可以接受学生提交内容的作业流项类型。CourseWork 资源包含说明、截止日期、最高成绩等详细信息，以及创建时间等元数据。

每个 CourseWork 资源都描述了以下类型的任务之一：

• 学生通过提交工作表或其他附件来完成的作业。
• 简答题或选择题。

CourseWork 项的学生作业由 StudentSubmission 表示。它包含一个响应和额外的元数据，例如状态和分配的成绩。

StudentSubmission 的内容取决于相应 CourseWork 项的类型，可以包括：

• 为作业提交的工作表和附件，包括其标题、缩略图和网址，以及可与相应 API（例如 Drive 或 YouTube）搭配使用的标识符。
• 简答题或选择题的回答。

如需详细了解如何管理作业和学生提交的内容，请参阅管理作业。

CourseWorkMaterials 和 Announcements

与 CourseWork 类似，CourseWorkMaterials 表示分配给课程中一组学生的内容。每项资源都有详细信息（例如标题和说明）以及补充材料。不过，与 CourseWork 不同，CourseWorkMaterials 不需要学生提交任何数据制品。因此，CourseWorkMaterials 没有截止日期，也不存在 StudentSubmissions。教师可能会使用 CourseWorkMaterials 发布建议的读物、课程大纲或课堂规则。

Announcements 也表示与一组学生共享的内容，但没有标题等详细信息，并且无法按 Topics（例如 CourseWork 或 CourseWorkMaterials）进行整理。教师可能会使用这些帖子向班级发布提醒或通知。

主题

Topics 用于直观地整理课程中的 CourseWork 和 CourseWorkMaterials。例如，您可以使用这些标签将作业分组为“选做”和“必做”，或“第 1 单元”和“第 2 单元”。

Google 课堂插件

插件是由开发者提供的界面和后端，通常显示在 iframe 中。附加内容会显示为动态中的附件。流项可以是任何 Announcements、CourseWork 或 CourseWorkMaterials。附加附件由 AddOnAttachment 表示。

插件附件可以是活动或内容。

• 对于作业附件，学生需要完成并提交个人作业。例如测验、绘画或游戏。您可以选择是否对提交的作业进行评分。
• 内容附件不需要学生提交。学生无需上交附件，也不会获得评分。例如照片、文章和视频。

如需了解详情，请参阅插件开发指南。

注册

应用可以订阅通知，以便在 Google 课堂中的特定数据发生变化时收到通知。例如，当课程的员工名单更新时。 Registrations 表示向您的应用发送这些通知的指令。

如需了解详情，请参阅推送通知指南。