Classroom API 提供了 RESTful 接口,方便您在 Google 课堂中管理课程和学生名单。此外,开发者和内容所有者还可以通过“课堂”分享按钮将内容分享到“课堂”。
哪些人可以使用该 API ?
Google Workspace 教育版网域管理员可以使用此 API 代表教师以编程方式配置课程,将学生信息系统与 Google 课堂同步,并基本了解网域中所教授的课程。
应用开发者可以使用 Classroom API 将其应用与 Google 课堂集成。这些应用需要使用 OAuth 2.0 来请求查看教师的课程和学生名单的权限。管理员可以限制网域中的教师和学生是否可以授权应用访问其 Google 课堂数据。
网站所有者和内容开发者可以使用“课堂”分享按钮,让学生和教师将内容发回“课堂”。
所有 API 和 Google 课堂分享按钮集成均应遵循 Google 课堂品牌推广指南。
API 概览
Classroom API 包含多种实体类型,它们与 Google 课堂界面中的课程、教师和学生相对应。除了 Google 课堂中现有的资源外,部分实体还具有该 API 特有的额外属性。主要实体类型包括:
如需详细了解该 API 的资源和方法,请参阅 Classroom API 参考文档。
课程元数据和别名
“课程”代表一个类,例如“M. 史密斯的第四期数学课”及其指定教师、学生名单和元数据。每个课程都由服务器分配的唯一 ID 进行标识。具体来说,课程资源封装了课程的所有相关元数据,例如名称、说明、地点和时间。课程的学生名单是通过学生、教师和邀请资源及其方法进行管理的。
别名是类的替代标识符,可能与课程关联,用于替代唯一 ID。每个别名都存在于一个命名空间中,用于限制谁可以创建和查看该别名。支持两种命名空间:
- 网域:网域命名空间有助于创建所有用户都需要访问但不特定于任何程序的别名。例如,课程的备用产品详情(例如 MATH 127 和 COMSCI 127)应在网域命名空间中创建。网域命名空间中的别名只能由网域管理员创建,但对网域中的所有用户可见。
- 开发者项目:开发者项目命名空间对于管理特定于应用的别名很有用。例如,为课程使用备用标识符的应用可以创建别名,以将其标识符映射到 Google 课堂课程。在此命名空间中创建的别名与特定 Google API 控制台相关联。应用的任何用户都可以在该应用的开发者项目的命名空间中创建和查看别名。
如需详细了解如何管理课程元数据和别名,请参阅管理课程。
课程的学生名单和用户
“学生”和“教师”是用户个人资料与课程之间的具体映射,表示该用户在课程中的角色。指定学生和教师不具有全局性:用户可以为一门课程指定教师,为另一门课程指定学生。“学生”或“教师”标识是特定课程中特定用户的一组权限。
- 学生
- 学生资源表示已注册为特定课程的学生的用户。学生可以查看该课程的课程详情和教师。
- 教师
- 教师资源表示讲授特定课程的用户。教师可以查看和更改课程详细信息、查看教师和学生,以及管理其他教师和学生。
邀请及其关联方法提供了一种将学生和教师添加到课程的便捷方式。通过创建邀请,用户可以选择是否加入课程,而非通过教师和学生资源直接添加。
UserProfiles 表示映射到用户网域个人资料(由 Directory API 所返回的用户唯一 ID 或电子邮件地址进行标识)。当前用户还可以使用 "me"
简写形式引用自己的 ID。
如需详细了解如何管理学生名单,请参阅管理教师和学生。
课程作业和学生提交的内容
CourseWork 项表示分配给课程中一组学生的单个任务。它包含说明、截止日期、资料等详细信息以及创建时间等元数据。材料包括标题、缩略图和网址,以及可与相应 API(即云端硬盘、YouTube)搭配使用的标识符。
CourseWork 项描述了以下其中一种任务:
- 学生通过提交工作表或其他附件来完成的作业。
- 简答题或单选题。
CourseWork 内容的学生作业由 StudentSubmission 表示。它由响应和额外的元数据(例如状态和已分配的成绩)组成。
StudentSubmission 的内容取决于相应的 CourseWork 项的类型:
- 为作业提交的工作表和附件,包括标题、缩略图和网址,以及可与相应的 API(例如云端硬盘或 YouTube)搭配使用的标识符。
- 简答题或单选题的回答。
如需详细了解如何管理课程作业和学生提交的作业,请参阅管理课业。
快速入门
如需设置您的环境并立即开始使用该 API,请尝试使用以下任一快速入门:
使用 Classroom API Explorer 进行实验
如需对实际数据进行调用方法实验,请尝试使用 Classroom API Explorer。您无需编写任何代码即可开始使用,但请注意,您使用 API Explorer 执行的操作可以修改现有数据。
开始调用这些方法的一种方法是调用 courses.list()
方法。此方法不需要任何请求参数,您可以从返回的课程列表中检索 id
以用作其他 API 调用的请求参数。如果您没有任何课程,可以使用 courses.create()
方法创建一个。
您还可以浏览 API 参考文档。