本頁將介紹建立附件及使用學生繳交的作業詳細資料。請注意,提出這些要求時,您可能需要提供附件相關參數。
建立連結
向適當的 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
值,或將其設為 0,藉此停用附件的成績回傳功能。
設定繳交作業的成績
您可以傳送 PATCH
要求至 courses.courseWork.addOnAttachments.studentSubmissions
端點,來修改學生提交的內容。要求主體必須包含含有修改值的 AddOnAttachmentStudentSubmission
執行個體。設定 pointsEarned
欄位即可修改繳交成績。老師在 Classroom UI 中會看到在 pointsEarned
中傳送的值成為「草稿成績」。老師可以在發還作業給學生前修改草稿成績如要進一步瞭解如何向老師顯示成績,請參閱「Classroom UI 中的評分總覽」。
請注意,只有在下列情況下,您才能使用 pointsEarned
設定成績:
- 附件的
maxPoints
值必須是正數。 - 這個外掛程式必須是附件的原始建立者。
請注意,您也可以向 addOnAttachments
端點發出 PATCH
要求,修改已經建立的 AddOnAttachment
的 maxPoints
值。
設定成績的時機
您可以選擇將成績退回 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
欄位設定。如果您的產品允許老師編輯特定活動的學生分數,建議您進行檢查,並在必要時更新這個值。