与附件互动

本页面讨论了创建附件的实现详情，以及 处理学生提交的作业。请注意，您可能需要提供 附件相关参数。

创建连接

向相应应用发出 CREATE 请求，以创建连接 courses.*.addOnAttachments.create 端点。您的请求必须包含 请求正文中 AddOnAttachment 的实例。

创建连接时，以下字段是必填字段：

  • title：附件的字符串名称。
  • teacherViewUri：附件的教师视图的 URI。
  • studentViewUri：附件的学生视图的 URI。
  • studentWorkReviewUri：供教师查看学生作业的 URI 附件。只有活动类型的附件才需要此字段。

您可能需要添加以下可选字段：

  • dueDate 和 dueTime（如果指定附件的截止日期）。
  • maxPoints：附件的最高成绩。必须是非零值 如果您想支持成绩回传适用于活动类型的附件 。

如需详细了解这些字段，请参阅 AddOnAttachment 资源参考文档。

学生提交内容的详细信息

典型的提交工作流程如下：

  1. 学生启动 studentViewUri 以完成一项活动。
  2. 该插件会从 getAddOnContext 方法中检索 submissionId。 使用学生凭据登录
  3. submissionId 和 attachmentId 由该插件存储 developer 作为学生作业的唯一标识符。发生以下情况时 教师在 Google 课堂中复制了作业，您就可以使用 这两个参数的复合键，用于在 复制的作业。如需了解详情，请参阅我们关于复制内容的页面。
  4. 一位有兴趣评阅学生作业的教师启动了 studentWorkReviewUri。该请求包含以下查询参数： courseId、itemId、itemType、attachmentId和submissionId。
  5. 插件开发者会使用这四个 ID 检索学生的作业。使用 courses.courseWork.addOnAttachments.studentSubmissions 端点 检索或修改有关学生提交内容的信息。
。

检测提交状态

将GET请求发送到 courses.courseWork.addOnAttachments.studentSubmissions 端点以获取 特定 submissionId 的详细信息。您收到 AddOnAttachmentStudentSubmission 对象，该对象包含提交内容的成绩 (pointsEarned) 和当前状态 (postSubmissionState)。提交状态 可以是下列值之一：

  • NEW（如果学生从未访问过提交内容）。
  • CREATED（如果学生已创建提交内容但尚未提交）。
  • TURNED_IN（如果学生已向教师提交作业）。
  • RETURNED（如果教师已将提交内容发回给学生）。
  • RECLAIMED_BY_STUDENT（如果学生“已取消提交”）自己的工作。

您可以使用此端点检测插件中学生作业的状态。您 然后根据学生的选择，调整提供给学生的视图或选项。 状态。这可能包括以下功能：

  • 在插件中显示作业的上交状态。这可能会 帮助学生避免可能误解的情况 无法上交作业。
  • 限制提交内容修改权限。如果作业的状态为 CREATED或RECLAIMED_BY_STUDENT，学生可能可以修改 提交的内容。如果作业的状态为“TURNED_IN”或“RETURNED”， 学生可能无法修改其提交内容。

成绩和多个附件

为单个附件设置成绩时只能使用一个插件附件 分配。如果教师创建了多个 提供了 maxPoints 值，则只有第一个此类附件可以设置 作业成绩。请勿设置 maxPoints 值，也可以将此值设为 0 停用附件的成绩回传功能。

设置提交内容的成绩

您可以向PATCH courses.courseWork.addOnAttachments.studentSubmissions 端点。请求 正文必须包含一个带有AddOnAttachmentStudentSubmission 修改过的值。设置 pointsEarned 字段以修改提交内容的成绩。 pointsEarned 中传递的值将成为面向以下学生的初始成绩： 教师。教师可以修改初始成绩 然后再将作业发回给学生。请参阅 Google 课堂界面：详细了解成绩计算方式 呈现给教师的信息

请注意，仅当满足以下条件时，您才能使用 pointsEarned 设置成绩 true：

  • 附件的 maxPoints 值必须为正值。
  • 插件必须是附件的原始创建者。

另请注意，您可以修改已创建的 AddOnAttachment 的 maxPoints 方法是向 addOnAttachments 端点发出 PATCH 请求。

何时设置成绩

您可以选择何时将成绩回传到 Google 课堂。通过 关键区别在于您是否选择存储教师的凭据， 只有教师可以修改成绩。

有两个附加的时刻，您可以在相应时刻将成绩传递给 Google 课堂：当学生完成作业或老师时 在学生作业批改 iframe 中打开学生的作业。

如果您想在学生完成作业时设置成绩，则必须存储 检索教师的离线凭据，并使用它们来修改成绩 在学生完成作业时触发。通过这种方法， 好处：

  • 提供无缝的成绩更新。教师不需要参加任何 操作，让系统在 Google 课堂界面中填充成绩。
  • 实时了解班级在作业中的进度。 通过设置在学生完成附件时给出成绩，教师可以理解 的学生的而无需打开每个提交内容。

请注意，此方法还允许使用异步方法 同步。您可以定期轮询 AddOnAttachmentStudentSubmission 端点来检测学生提交作业的时间。修改 则使用存储的凭据设置提交内容的成绩。

如果您不想在学生会话期间加载教师的凭据， 当当前教师加载学生的 学生作业回顾 iframe 中提交的内容。不过，这样可能无法提供 Google 课堂界面中的评分功能提供特别流畅的用户体验 不会实时更新，教师必须打开 提交内容的学生作业回顾 iframe。

检测作业成绩的变化

教师可以在 创建作业后 Google 课堂。此类修改可能会导致 包括：

  • 更改指定的分值。
  • 更改作业的 maxPoints 值。
  • 更改是否应为作业评分。

要查看作业的当前评分设置，我们建议您将 向 courses.courseWork 端点发出 GET 请求。响应包括 当前的 maxPoints 值。不计分的作业为 null 或 0 maxPoints 值。

如果您已将成绩传回 Google 课堂，请使用 courses.courseWork.addOnAttachments.studentSubmissions 端点来获取或 更改插件附件的成绩。成绩值是使用 pointsEarned 字段。请考虑检查并根据需要更新此值 如果您的产品允许教师修改学生在特定领域 活动。