本页面讨论了创建附件和处理学生提交的作业的实现详情。请注意,在发出这些请求时,您可能需要提供与连接相关的参数。
创建连接
向相应的 courses.*.addOnAttachments.create
端点发出 CREATE
请求,以创建连接。请求必须在请求正文中包含 AddOnAttachment
实例。
创建连接时,以下字段是必填字段:
title
:附件的字符串名称。teacherViewUri
:附件的教师视图的 URI。studentViewUri
:附件的学生视图的 URI。studentWorkReviewUri
:供教师查看学生在附件中完成作业的 URI。只有活动类型的附件才需要此字段。
您可能需要添加以下可选字段:
dueDate
和dueTime
(如果指定附件的截止日期)。maxPoints
:附件的最高成绩。如果您想支持成绩回传,则必须为非零值。仅适用于 activity 类型的附件。
如需详细了解这些字段,请参阅 AddOnAttachment
资源参考文档。
学生提交内容的详细信息
典型的提交工作流程如下:
- 学生启动
studentViewUri
以完成一项活动。 - 该插件使用学生凭据从
getAddOnContext
方法中检索submissionId
。 submissionId
和attachmentId
由插件开发者存储为学生作业的唯一标识符。如果教师在 Google 课堂中复制了作业,您可以使用这两个参数的复合键在复制的作业中显示新附件。如需了解详情,请参阅我们关于复制内容的页面。- 有兴趣审核学生作业的教师启动
studentWorkReviewUri
。该请求包含以下查询参数:courseId
、itemId
、itemType
、attachmentId
和submissionId
。 - 插件开发者会使用这四个 ID 检索学生的作业。使用
courses.courseWork.addOnAttachments.studentSubmissions
端点可检索或修改有关学生提交内容的信息。
检测提交状态
向 courses.courseWork.addOnAttachments.studentSubmissions
端点发出 GET
请求,以获取有关特定 submissionId
的详细信息。您会收到一个 AddOnAttachmentStudentSubmission
对象,其中包含提交内容的成绩 (pointsEarned
) 和当前状态 (postSubmissionState
)。提交状态可以是以下值之一:
NEW
(如果学生从未访问过提交内容)。CREATED
(如果学生已创建提交内容但尚未提交)。TURNED_IN
(如果学生已向教师提交作业)。RETURNED
(如果教师已将提交内容发回给学生)。- 如果学生“已取消提交”作业,则为
RECLAIMED_BY_STUDENT
。
您可以使用此端点检测插件中学生作业的状态。然后,您可以根据返回的状态调整提供给学生的视图或选项。这可能包括以下功能:
- 在插件中显示作业的上交状态。这有助于学生避免可能感到困惑,并确保不会误交作业。
- 限制提交内容修改权限。如果作业的状态为
CREATED
或RECLAIMED_BY_STUDENT
,学生可以修改其提交内容。如果作业的状态为TURNED_IN
或RETURNED
,学生可能无法修改其提交内容。
成绩和多个附件
为单个作业设置成绩时只能使用一个插件附件。如果教师创建了多个提供 maxPoints
值的活动类型附件,则只有第一个此类附件可以设置作业成绩。您可以不设置 maxPoints
值,也可以将其设为 0 以停用附件的成绩回传功能。
设置提交内容的成绩
您可以通过向 courses.courseWork.addOnAttachments.studentSubmissions
端点发送 PATCH
请求来修改学生提交的作业。请求正文必须包含一个具有修改后的值的 AddOnAttachmentStudentSubmission
实例。设置 pointsEarned
字段以修改提交内容的成绩。
pointsEarned
中传递的值将成为在 Google 课堂界面中向教师显示的初始成绩。教师可以先修改初始成绩,然后再将作业发回给学生。请参阅“课堂”界面中的评分概览,详细了解如何向教师显示成绩。
请注意,只有在满足以下条件时,才能使用 pointsEarned
设置成绩:
- 附件的
maxPoints
值必须为正值。 - 插件必须是附件的原始创建者。
另请注意,您可以通过向 addOnAttachments
端点发出 PATCH
请求来修改已创建的 AddOnAttachment
的 maxPoints
值。
何时设置成绩
您可以选择何时将成绩回传到 Google 课堂。关键区别在于您是否选择存储教师的凭据,因为只有教师才能修改成绩。
在两个插件时刻,您可以向 Google 课堂传递成绩:学生完成作业时,或教师在学生作业评价 iframe 中打开学生的作业。
如果要在学生完成作业时设置成绩,您必须存储教师的离线凭据,然后在学生完成作业时检索并使用它们来修改成绩。此方法具有以下潜在优势:
- 提供无缝的成绩更新。教师无需执行任何特殊操作即可在 Google 课堂界面中填充成绩。
- 实时了解课程作业的进度。 通过在学生完成附件时为学生设置成绩,教师无需打开每个提交内容,即可了解学生的理解程度。
请注意,这种方法还允许使用异步方法对同步进行评分。您可以定期轮询 AddOnAttachmentStudentSubmission
端点,以检测学生何时提交作业。提交作业后,使用存储的凭据设置作业的成绩。
如果您不想在学生会话期间加载教师的凭据,可以在活跃教师在学生作业评价 iframe 中加载学生提交的作业时使用其凭据。但是,这样可能无法提供特别顺畅的用户体验,因为 Google 课堂界面中的成绩不会实时更新,教师需要打开每次提交的学生作业评价 iframe。
检测作业成绩的变化
创建作业后,教师可以在“课堂”中修改成绩设置此类修改可能包括:
- 更改指定的分值。
- 更改作业的
maxPoints
值。 - 更改是否应为作业评分。
如需查看作业的当前评分设置,我们建议您向 courses.courseWork
端点发送 GET
请求。响应包含当前的 maxPoints
值。不计分的作业的 maxPoints
值为零或零。
如果您已将成绩传回 Google 课堂,请使用 courses.courseWork.addOnAttachments.studentSubmissions
端点提取或更改插件附件的成绩。成绩值使用 pointsEarned
字段设置。如果您的产品允许教师修改学生在特定活动的得分,请考虑检查并在必要时更新此值。