本頁面將討論建立附件的實作詳細資料、使用者開啟附件時的建議動作，以及如何處理學生的提交內容。請注意，提出這些要求時，您可能需要提供附件相關參數。
建立連結
向適當的 CREATE 端點發出 courses.*.addOnAttachments.create 要求，即可建立附件。要求主體必須包含 AddOnAttachment 的例項。
建立附件時，必須填寫下列欄位：
title：附件的字串名稱。teacherViewUri：附件的老師檢視畫面 URI。studentViewUri：附件學生檢視畫面的 URI。studentWorkReviewUri：老師查看學生附件作業的 URI。只有活動類型的附件才需要填寫這個欄位。
您可能需要加入下列選填欄位：
- 指定附件到期時間時，必須提供
dueDate和dueTime。 maxPoints：附件的最高等級。如要支援成績回傳，必須為非零值。僅適用於活動類型附件。
如要進一步瞭解這些欄位，請參閱 AddOnAttachment 資源參考資料。
驗證使用者憑證和角色
學生檢視畫面 iframe、學生作業審查 iframe 和老師檢視畫面 iframe 的用途都是向使用者呈現內容，而非修改 Classroom 作業。開啟其中一個檢視畫面時，建議採取下列做法：
- 取得使用者的 OAuth 憑證。
- 根據
itemType提出courseWork.getAddOnContext、courseWorkMaterials.getAddOnContext或announcements.getAddOnContext要求，驗證使用者角色。 - 檢查回應，確認是否出現
TeacherContext或StudentContext。系統只會傳回一個值，對應使用者在課程中的角色。 - 如果目前使用者是學生，且
itemType為courseWork，請記錄回應中的submissionId，並附上學生的作業。外掛程式 iframe 必須submissionIds相符，才能將成績傳回 Classroom，並在評分工具中向老師顯示學生作業。 - 如果外掛程式已知道
attachmentId，請顯示適當的附件 UI。 - 否則，這個附件必須是從其他串流項目或課程複製而來。如需這類情況的建議，請參閱「處理複製的內容」指南。
學生繳交作業的詳細資料
一般提交工作流程包含下列步驟：
- 學生啟動
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 值設為零或保留未設定狀態。
設定作業的成績
您可以向 courses.courseWork.addOnAttachments.studentSubmissions 端點傳送 PATCH 要求，修改學生的作業。要求主體必須包含 AddOnAttachmentStudentSubmission 的例項，以及修改過的值。設定 pointsEarned 欄位，修改提交內容的分數。
在 pointsEarned 中傳遞的值會成為草稿成績，顯示在 Classroom 使用者介面中，供老師查看。老師可以在將作業發還給學生前修改暫定成績。如要進一步瞭解老師如何查看成績，請參閱「Classroom 使用者介面中的評分功能簡介」。
請注意，只有在下列情況下，您才能使用 pointsEarned 設定成績：
- 附件必須有正值的
maxPoints。 - 外掛程式必須是附件的原創者。
另請注意，您可以對 addOnAttachments 端點發出 PATCH 要求，藉此修改已建立 AddOnAttachment 的 maxPoints 值。
設定成績的時機
您可以選擇何時將成績傳回 Google Classroom。重要區別在於您是否選擇儲存老師的憑證，因為只有老師可以修改成績。
您可以在兩個外掛程式時刻將成績傳遞至 Google Classroom：學生完成作業時，或是老師在「學生作業審查」iframe 中開啟學生的作業時。
如要在學生完成作業時設定成績，您必須儲存老師的離線憑證，然後在學生完成作業時擷取並使用該憑證來修改成績。這個方法可能帶來以下優點：
- 提供無縫的成績更新。老師無須採取任何特別行動，系統就會在 Classroom 使用者介面中填入成績。
- 即時掌握班級作業進度。老師可以在學生完成附件後設定成績，不必開啟每份提交內容，就能掌握學生的理解程度。
請注意，這個方法也允許非同步方法來同步處理成績。您可能會定期輪詢 AddOnAttachmentStudentSubmission 端點，偵測學生何時繳交作業。提交後，請使用儲存的憑證設定提交內容的分數。
如果不想在學生工作階段載入老師的憑證，可以在老師於「學生作業審查」iframe 載入學生的提交內容時，使用老師的有效憑證。不過，由於 Classroom 使用者介面中的成績不會即時更新，且老師必須開啟每份作業的「學生作業審查」iframe，因此這種做法可能無法提供特別流暢的使用者體驗。
偵測作業成績變更
作業建立後，老師可以在 Classroom 中編輯成績設定。這類編輯可能包括：
- 變更指定分數值。
- 變更作業的
maxPoints值。 - 變更是否要為作業評分。
如要查看作業目前的評分設定，建議您將 GET 要求傳送至 courses.courseWork 端點。回應會包含目前的 maxPoints 值。未評分的作業具有空值或零分 maxPoints 值。
如果已將成績傳回 Classroom，請使用 courses.courseWork.addOnAttachments.studentSubmissions 端點擷取或變更外掛程式附件的成績。系統會使用 pointsEarned 欄位設定等級值。如果產品允許老師編輯特定活動的學生分數，請考慮檢查並視需要更新這個值。