本頁將介紹建立附件及使用學生繳交的作業詳細資料。請注意，您可能需要在提出這些要求時提供附件相關參數。
建立連結
向適當的 courses.*.addOnAttachments.create 端點發出 CREATE 要求，建立附件。要求內容必須包含 AddOnAttachment 的例項。
建立附件時，下列欄位為必填：
title：附件的字串名稱。teacherViewUri：附件的教師檢視畫面的 URI。studentViewUri：附件的學生檢視畫面 URI。studentWorkReviewUri：老師用來查看學生附件作業的 URI。只有活動類型附件需要填寫這個欄位。
建議您加入下列部分選填欄位：
dueDate和dueTime(如果指定附件的到期日)。maxPoints：附件的最高評分。如要支援成績回傳，則必須為非零值。僅適用於活動類型附件。
如要進一步瞭解這些欄位，請參閱 AddOnAttachment 資源參考資料。
學生繳交作業的詳細資料
提交內容的一般工作流程如下：
- 學生啟動
studentViewUri來完成活動。 - 這個外掛程式使用學生憑證，從
getAddOnContext方法擷取submissionId。 submissionId和attachmentId會由外掛程式開發人員儲存，做為學生作業的專屬 ID。如果老師在 Classroom 中複製作業，您可以使用這兩個參數的複合鍵，在複製的作業中顯示新附件。詳情請參閱「複製內容」頁面。- 有意查看學生作業的老師會啟動
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 值設為未設定或設為零，以停用附件成績回傳功能。
設定繳交作業的成績
如要修改學生提交的內容，請將 PATCH 要求傳送至 courses.courseWork.addOnAttachments.studentSubmissions 端點。要求主體必須包含 AddOnAttachmentStudentSubmission 的例項，並包含經修改的值。設定 pointsEarned 欄位，修改繳交作業的成績。在 pointsEarned 中傳遞的值會成為草稿成績，老師可在 Classroom 使用者介面中查看。老師可以在將作業發還給學生前修改草稿成績。如要進一步瞭解如何向老師呈現成績，請參閱「Classroom UI 中的成績總覽」。
請注意，您只能在下列情況下使用 pointsEarned 設定等級：
- 附件的
maxPoints值必須是正數。 - 這個外掛程式必須是附件的原始建立者。
另請注意，如要修改已建立的 AddOnAttachment 的 maxPoints 值，您可以向 addOnAttachments 端點發出 PATCH 要求。
設定成績的時機
您可以選擇將成績退回 Google Classroom。主要的區別在於，是否選擇儲存老師的憑證，因為只有老師可以修改成績。
您可以在兩個附加時刻將成績傳送給 Google Classroom：當學生完成作業，或者老師在學生作業審查 iframe 中開啟學生作業時。
如果您想在學生完成作業時設定成績，必須儲存老師的離線憑證，然後在學生完成作業時擷取並使用這些憑證修改成績。這種方法具有以下潛在優點：
- 提供無縫的成績更新功能。老師無須採取任何特殊行動，即可將成績填入 Classroom UI。
- 透過作業即時掌握班級進度。學生提交附件後，老師就能設定成績，無須打開每份提交內容，就能掌握學生的學習狀況。
請注意，這個方法也允許非同步方法來同步評分。您可以定期輪詢 AddOnAttachmentStudentSubmission 端點，偵測學生提交作業的時間。提交後，請使用儲存的憑證設定提交作業的成績。
如果您不想在學生工作階段中載入老師的憑證，可以在老師在學生作業審查 iframe 中載入學生提交的內容時，使用有效老師的憑證。不過，由於 Classroom UI 中的成績不會即時更新，且老師必須開啟每份提交內容的「學生作業評論」iframe，因此這可能無法提供特別流暢的使用者體驗。
偵測作業成績的變更
老師可以在建立作業後，編輯 Classroom 中的成績設定。這類編輯可能包括：
- 變更指定的分數值。
- 變更指派的
maxPoints值。 - 變更是否要批改作業。
如要查看作業目前的評分設定，建議您將 GET 要求傳送至 courses.courseWork 端點。回應中會包含目前的 maxPoints 值。未評分的作業有空值或零的 maxPoints 值。
如果您已將成績傳回 Classroom，請使用 courses.courseWork.addOnAttachments.studentSubmissions 端點擷取或修改外掛程式附件的成績。系統會使用 pointsEarned 欄位設定等級值。如果您的產品允許老師編輯特定活動的學生分數，建議您進行檢查，並在必要時更新這個值。