Classroom UI 支援「五種」課堂作業類型,包括作業、測驗作業、簡答問題、選擇題和教材。Classroom API 目前支援「三種」這三種類型,在 API 中稱為 CourseWorkType
:作業、簡答問題和選擇題。
Materials
附加至 CourseWorkType
資源:作業、簡答問題和選擇題。
如要使用這項功能,您可以使用 CourseWork 資源代表在特定課程中指派給學生的作業或問題,包括任何其他教材和詳細資料,例如截止日或最高分數。
除了 CourseWork 資源外,您也可以使用 StudentSubmission
資源管理已完成的作業。以下各節將詳細說明這些細節。
建立作業
「只能」代表課程的老師建立作業,並嘗試在課程中代表學生建立作業,將導致 403 PERMISSION_DENIED
錯誤。同樣地,網域管理員也無法為自己並未教授或嘗試透過 API 的課程建立指派作業,也會導致 403 PERMISSION_DENIED
錯誤。
使用 courses.courseWork.create
方法建立指派作業時,您可以將連結以 materials
形式附加,如以下程式碼範例所示:
Java
Python
結果包含伺服器指派 ID,可用來參照其他 API 要求中的指派作業。
如要在透過 Classroom API 建立的作業中加入已連結的教材,請使用連結資源並指定目標網址。Classroom 會自動擷取標題和縮圖。 Classroom API 也原生支援 Google 雲端硬碟和 YouTube 教材,可加入以類似方式加入 DriveFile 資源或 YouTubeVideo 資源的 Google 雲端硬碟和 YouTube 教材。
如要指定截止日,請將 dueDate
和 dueTime
欄位設為對應的世界標準時間時間。截止日必須是未來的日期。
擷取作業和問題
您可以為對應課程的師生或網域管理員擷取作業和問題。如要擷取特定作業或問題,請使用 course.courseWork.get。如要擷取所有指派作業或問題 (可選擇符合某些條件),請使用 courses.courseWork.list。
所需範圍取決於要求使用者在課程中具備的角色。如果使用者是學生,請使用下列其中一個範圍:
https://www.googleapis.com/auth/classroom.coursework.me.readonly
https://www.googleapis.com/auth/classroom.coursework.me
如果使用者是老師或網域管理員,請使用以下任一範圍:
https://www.googleapis.com/auth/classroom.coursework.students.readonly
https://www.googleapis.com/auth/classroom.coursework.students
擁有擷取作業或問題的權限,不代表存取教材或素材中繼資料的權限。實際上,這表示管理員若不是課程成員,可能無法看到附加的雲端硬碟檔案標題。如要允許管理員存取使用者檔案,請參閱全網域委派指南。
管理學生的作答內容
StudentSubmission
資源代表學生完成的作業或問題的成績,建立新問題或指派作業時,系統會自動為每位學生建立 StudentSubmission
資源。
以下各節說明管理學生作答內容時常用的操作。
擷取學生回覆
學生可以擷取自己的繳交作業,老師可以擷取課程中所有學生的繳交的作業,而網域管理員則可擷取網域中所有學生的提交內容。系統會為學生提交的每個作業指派一個 ID;如果您知道這組 ID,請使用 courses.courseWork.studentSubmissions.get
擷取該 ID。
使用 courses.courseWork.studentSubmissions.list
方法取得符合特定條件的 StudentSubmission
資源,如以下範例所示:
Java
Python
指定 userId
參數,即可擷取屬於特定學生的 StudentSubmission
資源,如以下範例所示:
Java
Python
系統會根據 Google Admin SDK 傳回的使用者專屬 ID 或電子郵件地址來識別學生。目前使用者也可以使用 "me"
(簡寫) 參照自己的 ID。
您也可以在課程內取得學生繳交的所有作業。方法是使用常值 "-"
做為 courseWorkId
,如下列範例所示:
Java
service.courses().courseWork().studentSubmissions()
.list(courseId, "-")
.set("userId", userId)
.execute();
Python
service.courses().courseWork().studentSubmissions().list(
courseId=<course ID or alias>,
courseWorkId='-',
userId=<user ID>).execute()
所需範圍取決於要求使用者在課程中具備的角色。如果使用者是老師或網域管理員,請使用以下範圍:
https://www.googleapis.com/auth/classroom.coursework.students.readonly
https://www.googleapis.com/auth/classroom.coursework.students
如果使用者是學生,請使用以下範圍:
https://www.googleapis.com/auth/classroom.coursework.me.readonly
https://www.googleapis.com/auth/classroom.coursework.me
擁有擷取學生繳交內容的權限不代表存取附件或附件中繼資料的權限。在實際執行上,這表示管理員不是課程的成員,可能無法看到附加的雲端硬碟檔案標題。如要允許管理員存取使用者檔案,請參閱全網域委派指南。
在學生的回覆中新增附件
您可以在學生繳交的作業中附加 Link
、DriveFile
或 YouTubeVideo
資源的連結。方法是使用 courses.courseWork.studentSubmissions.modifyAttachments
,如以下範例所示:
Java
Python
連結附件是由目標網址定義;Classroom 會自動擷取標題和縮圖圖片。您可以前往各自的參考資料頁面,瞭解其他資料。
只有課程老師或擁有該課程的學生才能修改 StudentSubmission
。只有在學生繳交作業的 CourseWorkType
為 ASSIGNMENT
時,您才能附加 Materials
。
所需範圍取決於要求使用者在課程中具備的角色。如果使用者是老師,請使用以下範圍:
https://www.googleapis.com/auth/classroom.coursework.students
如果使用者是學生,請使用以下範圍:
https://www.googleapis.com/auth/classroom.coursework.me
管理學生回覆狀態
學生回覆的內容可能無法繳交、繳交或發還。StudentSubmission
中的狀態欄位代表目前的狀態。如要變更狀態,請呼叫下列其中一種方法:
courses.courseWork.studentSubmissions.turnIn
courses.courseWork.studentSubmissions.return
courses.courseWork.studentSubmissions.reclaim
這些方法全都會是空白的,示例:
Java
Python
service.courses().courseWork().studentSubmission().turnIn(
courseId=<course ID or alias>,
courseWorkId=<courseWork ID>,
id=<studentSubmission ID>,
body={}).execute()
只有擁有 StudentSubmission
的學生可以繳交或收回作業。
只能收回已繳交的作業。課程老師只能傳回處於繳交狀態的 StudentSubmission
。
批改學生作答內容
StudentSubmission
資源有兩個用來儲存成績的欄位:assignedGrade
(回報給學生的成績) 和 draftGrade
(只有老師看得到的暫定成績)。系統會使用 courses.courseWork.studentSubmissions.patch
更新這些欄位,並透過欄位遮罩包含適當的欄位,如以下範例所示。
Java
Python
studentSubmission = {
'assignedGrade': 99,
'draftGrade': 80
}
service.courses().courseWork().studentSubmissions().patch(
courseId=<course ID or alias>,
courseWorkId=<courseWork ID>,
id=<studentSubmission ID>,
updateMask='assignedGrade,draftGrade',
body=studentSubmission).execute()
使用 Classroom UI 時,老師必須先儲存草稿成績,才能指派成績。系統隨後會將指派的成績發還給學生。應用程式必須模擬這個行為。您的應用程式可透過下列任一方式批改學生作業:
僅指派
draftGrade
。舉例來說,如果想讓老師先手動查看成績,再確定成績,這個做法就很實用。學生無法查看暫定成績。同時指派
draftGrade
和assignedGrade
,以便為作業評分。
列出已指派的成績
透過探索 courses.courseWork.studentSubmissions.list
方法的回應物件,您可以列出特定課程項目的所有成績:
Java
Python
response = coursework.studentSubmissions().list(
courseId=course_id,
courseWorkId=coursework_id,
pageSize=10).execute()
submissions.extend(response.get('studentSubmissions', []))
if not submissions:
print('No student submissions found.')
print('Student Submissions:')
for submission in submissions:
print(f"Submitted at:"
f"{(submission.get('userId'), submission.get('assignedGrade'))}")