本页讨论了创建附件的实现细节、用户打开附件时的建议操作，以及如何处理学生提交的作业。请注意，您可能需要在发出这些请求时提供与附件相关的参数 。
创建附件
如需创建附件，请向相应的 courses.*.addOnAttachments.create 端点发出 CREATE 请求。您的请求必须在请求正文中包含 AddOnAttachment 的实例。
创建附件时必须包含以下字段：
title：附件的字符串名称。teacherViewUri：附件的教师视图的 URI。studentViewUri：附件的学生视图的 URI。studentWorkReviewUri：教师查看学生在附件上完成的作业的 URI。此字段仅适用于 activity 类型的附件。
您可能需要包含以下一些选填字段：
dueDate和dueTime（如果指定附件的截止日期和时间）。maxPoints：附件的最高成绩。如果您想支持成绩回传，则必须使用非零值。仅适用于 activity 类型的附件。
如需详细了解这些字段，请参阅 AddOnAttachment 资源参考文档。
验证用户凭据和角色
学生视图 iframe、学生作业查看 iframe和教师视图 iframe都是为了向用户呈现内容，而不是修改 Google 课堂作业。当其中一个视图打开时，请考虑执行以下操作：
- 获取用户的 OAuth 凭据。
- 根据
itemType发出courseWork.getAddOnContext、courseWorkMaterials.getAddOnContext或announcements.getAddOnContext请求，以验证用户角色。 - 检查响应，看看是否存在
TeacherContext或StudentContext。只能返回一个，对应于用户在课程中的角色。 - 如果当前用户是学生且
itemType为courseWork，请记录响应中学生作业的submissionId。submissionIds在插件 iframe 中匹配，并且是回传成绩以及在评分工具中向教师显示学生的作业所必需的。 - 如果插件已知道
attachmentId，则显示相应的附件界面。 - 否则，此附件必须是从其他信息流项或课程复制的。如需了解有关此场景的建议，请参阅处理复制的内容指南。
学生提交的作业详情
典型的提交工作流包含以下步骤：
- 学生启动
studentViewUri以完成 activity。 - 插件使用学生凭据从
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 值的 activity 类型的附件，则只有第一个此类附件可以设置作业成绩。将 maxPoints 值留空或将其设置为零，即可停用附件的成绩回传。
设置提交的作业的成绩
您可以通过向
courses.courseWork.addOnAttachments.studentSubmissions 端点发送 PATCH 请求来修改学生提交的作业。请求正文必须包含带有修改后的值的 AddOnAttachmentStudentSubmission 实例。设置 pointsEarned 字段以修改提交的作业的成绩。
在 pointsEarned 中传递的值会成为教师在 Google 课堂界面中看到的初始成绩 。教师可以在将作业发回给学生之前修改草稿成绩。如需详细了解如何向教师显示成绩，请参阅 Google 课堂界面中的评分概览。
请注意，只有在满足以下条件时，您才能使用 pointsEarned 设置成绩：
- 附件必须具有正
maxPoints值。 - 插件必须是附件的原始创建者。
另请注意，您可以通过向 addOnAttachments 端点发出 PATCH 请求来修改已创建的 AddOnAttachment 的 maxPoints 值。
何时设置成绩
您可以选择何时将成绩回传给 Google 课堂。关键区别在于您是否选择存储教师的凭据，因为只有教师才能修改成绩。
您可以在 两个插件时刻 将成绩传递给 Google 课堂：学生完成作业时，或教师在学生作业查看 iframe 中打开学生作业时。
如果您想在学生完成作业时设置成绩，则必须存储教师的离线凭据，然后在学生完成作业时检索并使用这些凭据来修改成绩。此方法具有以下潜在优势：
- 提供无缝的成绩更新。教师无需执行任何特殊操作即可在 Google 课堂界面中填充成绩。
- 实时了解课程的作业进度。 通过在学生完成附件时设置成绩，教师无需打开每个提交的作业即可了解学生的理解情况。
请注意，此方法还允许采用异步方法 进行成绩同步。您可以定期轮询 AddOnAttachmentStudentSubmission 端点，以检测学生何时提交了作业。提交后，使用存储的凭据设置提交的作业的成绩。
如果您不想在学生会话期间加载教师的凭据， 则可以在教师在学生作业查看 iframe 中加载学生提交的作业时使用活跃教师的凭据。不过，这可能无法提供特别流畅的用户体验，因为 Google 课堂界面中的成绩不会实时更新，并且教师需要打开每个提交的作业的学生作业查看 iframe。
检测作业成绩的变化
教师可以在创建作业后在 Google 课堂中修改成绩设置。此类修改可能包括：
- 更改分配的分数值。
- 更改作业的
maxPoints值。 - 更改作业是否应评分。
如需查看作业的当前评分设置，我们建议您发送
GET请求到courses.courseWork端点。响应包含当前的 maxPoints 值。未评分的作业的 maxPoints 值为 null 或零。
如果您已将成绩回传给 Google 课堂，请使用 courses.courseWork.addOnAttachments.studentSubmissions 端点获取或更改插件附件的成绩。成绩值是使用 pointsEarned 字段设置的。如果您的产品允许教师修改学生在特定 activity 中的得分，请考虑检查并根据需要更新此值。