與附件互動

本頁將說明建立附件及建立附件的實作詳細資料 處理學生繳交的作業請注意，您可能需要提供 附件相關參數。

建立連結

發送 CREATE 要求至適當的資料來建立附件 courses.*.addOnAttachments.create 端點。您的要求必須包含 要求主體中的 AddOnAttachment 例項。

建立附件時，必須提供下列欄位：

  • title：附件的字串名稱。
  • teacherViewUri：附件的教師檢視畫面 URI。
  • studentViewUri：附件的學生檢視畫面 URI。
  • studentWorkReviewUri：老師可查看學生作業的 URI 。只有活動類型附件才需要這個欄位。

建議您納入以下部分選用欄位：

  • dueDate 和 dueTime (如果指定附件的到期日)。
  • maxPoints：附件的最高成績。必須為非零的值 是否希望支援成績回傳功能。套用至活動類型附件 。

如要進一步瞭解這些欄位，請參閱 AddOnAttachment 資源參考資料。

學生繳交作業的詳細資料

一般的提交工作流程如下：

  1. 學生啟動 studentViewUri 來完成活動。
  2. 外掛程式會從 getAddOnContext 方法擷取 submissionId 存取學生憑證
  3. submissionId 和 attachmentId 是由外掛程式儲存 做為學生作業的專屬 ID。在： 老師在 Classroom 中複製作業時，您可以使用 這兩個參數的複合鍵，以在 已複製作業。詳情請參閱複製的內容頁面。
  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 中傳遞的值會成為草稿成績， 。老師可以修改暫定成績 ，再將作業發還給學生。如需評分總覽，請參閱這裡 Classroom UI：詳細瞭解成績狀況 簡報對象

請注意，您只能在下列情況下使用「pointsEarned」設定成績 是：

  • 附件的 maxPoints 值必須是正數。
  • 這個外掛程式必須是附件的原始建立者。

請注意，您也可以修改已建立的 AddOnAttachment 的 maxPoints 值，方法是向 addOnAttachments 端點發出 PATCH 要求。

設定成績的時機

您可以選擇將成績退回 Google Classroom。 但關鍵區別在於是否選擇儲存老師的憑證 只有老師可以修改成績。

大約有兩場附加片段，或許就能通過 Google Classroom：學生完成作業或當老師完成作業時 系統會在學生作業評量 iframe 中開啟學生的作業。

如要在學生完成作業時設定成績，您必須儲存 ，取得老師離線憑證，再擷取並使用這些憑證修改成績 學生完成作業時。這個方法提供一些 優點：

  • 提供順暢的成績更新服務。教師不需要 操作，讓系統在 Classroom UI 中填入成績。
  • 透過作業提供即時的深入分析，協助學生瞭解課程進度。 藉由設定學生完成附件時的成績，老師掌握相關知識 內容不必一一開啟每項提交內容，就能理解和瞭解

請注意，這個方法也允許使用非同步方式進行評分 同步處理。建議您定期輪詢 AddOnAttachmentStudentSubmission 偵測學生繳交作業的時間。之前 即可使用儲存的憑證設定作業成績。

如果您不想在學生工作階段中載入老師的憑證， 您就能在載入學生的 透過學生作業評量 iframe 提交內容。不過，這種做法可能無法 在 Classroom UI 中以成績的形式提供流暢的使用者體驗 都不會即時更新，因此老師必須在每個 學生作業評量的 iframe。

偵測作業成績變動

老師可以在 建立作業後的 Classroom。這類編輯 包括：

  • 變更指派的分數值。
  • 變更作業的 maxPoints 值，
  • 變更是否應批改作業。

如要查看作業目前的評分設定，建議您傳送 對 courses.courseWork 端點發出 GET 要求。回應包括 目前的 maxPoints 值。未評分的作業包含空值或零。 maxPoints 的值。

如果您已將成績退回 Classroom，請使用 要擷取的 courses.courseWork.addOnAttachments.studentSubmissions 端點，或 修改外掛程式附件的成績。成績值是使用 「pointsEarned」欄位。建議您檢查，並在必要時更新這個值 ，這是否可讓老師編輯學生在某方面的特定分數 活動。