老師為學生評分時，可以使用 rubric 範本
提交內容。Classroom API 可讓您代表
管理這些評分量表
圖 1. 查看 Classroom 作業的評分量表範例。
本指南說明 Rubrics API 的基本概念和功能。詳情請見 請參閱相關的說明中心文章，瞭解「一般 評分量表的架構與評分量表結構 評分作業。
必要條件
本指南假設您已具備下列項目：
- Python 3.8.6 以上版本
- pip 套件管理工具
- Google Cloud 專案。
- 擁有 Google Classroom 服務的 Google Workspace for Education 帳戶 啟用。
- 至少擁有一個測驗學生帳戶的測驗課程。如果您沒有 可以用於測試的 Classroom 課程 在使用者介面中建立 新增測試學生。
授權電腦版應用程式憑證
如要以使用者身分進行驗證，並存取應用程式中的使用者資料，您需要 建立一或多個 OAuth 2.0 用戶端 ID。用戶端 ID 可用來識別 單一應用程式傳送至 Google 的 OAuth 伺服器。如果您的應用程式在多個平台上運作 您都必須為每個平台分別建立用戶端 ID。
- 前往 存取 Google Cloud 控制台
- 按一下「建立憑證」>OAuth 用戶端 ID。
- 按一下「應用程式類型」>電腦版應用程式。
- 在「名稱」欄位中輸入憑證的名稱。這個名稱僅供 這項工具會顯示在 Google Cloud 控制台中例如「評分量表預覽用戶端」。
- 按一下「建立」，畫面上會顯示 OAuth 用戶端建立的畫面，其中顯示新的 用戶端 ID 和用戶端密碼。
- 依序點選「Download JSON」和「OK」。新建立的憑證 這組 ID 會顯示在 OAuth 2.0 用戶端 ID 之下。
- 將下載的 JSON 檔案儲存為
credentials.json，然後移動檔案到 工作目錄 - 按一下「建立憑證」>API 金鑰，並記下 API 金鑰。
詳情請參閱「建立存取認證」。
設定 OAuth 範圍
視專案現有的 OAuth 範圍而定，您可能需要 以及範圍
- 前往「OAuth 同意畫面」。
- 按一下「編輯應用程式」>儲存並繼續，返回「範圍」畫面。
- 按一下「新增或移除範圍」。
- 請新增下列範圍 (如果您尚未設定的話)：
https://www.googleapis.com/auth/classroom.coursework.studentshttps://www.googleapis.com/auth/classroom.courses
- 然後按一下「更新」>儲存並繼續 >儲存並繼續 > 返回資訊主頁。
詳情請參閱「設定 OAuth 同意畫面」一文。 內容。
classroom.coursework.students 範圍允許讀取及寫入
評分量表 (以及 CourseWork 的存取權) 和 classroom.courses 範圍
提供讀取及寫課程的功能
參考文件列出了特定方法所需的範圍
。請參閱 courses.courseWork.rubrics.create 授權範圍
舉例來說您可以在 Google 的 OAuth 2.0 範圍中查看所有 Classroom 範圍
API由於 API 仍在預先發布版，因此這裡未提及評分量表。
設定範例
在工作目錄中，安裝 Python 適用的 Google 用戶端程式庫：
pip install --upgrade google-api-python-client google-auth-httplib2 google-auth-oauthlib
建立名為 main.py 的檔案，以便建構用戶端程式庫並授權
使用 API 金鑰取代 YOUR_API_KEY：
import json
import os.path
from google.auth.transport.requests import Request
from google.oauth2.credentials import Credentials
from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError
# If modifying these scopes, delete the file token.json.
SCOPES = ['https://www.googleapis.com/auth/classroom.courses',
'https://www.googleapis.com/auth/classroom.coursework.students']
def build_authenticated_service(api_key):
"""Builds the Classroom service."""
creds = None
# The file token.json stores the user's access and refresh tokens, and is
# created automatically when the authorization flow completes for the first
# time.
if os.path.exists('token.json'):
creds = Credentials.from_authorized_user_file('token.json', SCOPES)
# If there are no (valid) credentials available, let the user log in.
if not creds or not creds.valid:
if creds and creds.expired and creds.refresh_token:
creds.refresh(Request())
else:
flow = InstalledAppFlow.from_client_secrets_file(
'credentials.json', SCOPES)
creds = flow.run_local_server(port=0)
# Save the credentials for the next run.
with open('token.json', 'w') as token:
token.write(creds.to_json())
try:
# Build the Classroom service.
service = build(
serviceName="classroom",
version="v1",
credentials=creds,
discoveryServiceUrl=f"https://classroom.googleapis.com/$discovery/rest?labels=DEVELOPER_PREVIEW&key={api_key}")
return service
except HttpError as error:
print('An error occurred: %s' % error)
if __name__ == '__main__':
service = build_authenticated_service(YOUR_API_KEY)
使用 python main.py 執行指令碼。系統會提示您登入
同意授予 OAuth 範圍
建立作業
評分量表已與作業 (或「CourseWork」) 建立關聯，
在該 CourseWork 的情境下產生意義評分量表只會在
建立父項 CourseWork 項目的 Google Cloud 專案。目的
請使用指令碼建立新的 CourseWork 作業。
將下列指令新增至 main.py：
def get_latest_course(service):
"""Retrieves the last created course."""
try:
response = service.courses().list(pageSize=1).execute()
courses = response.get("courses", [])
if not courses:
print("No courses found. Did you remember to create one in the UI?")
return
course = courses[0]
return course
except HttpError as error:
print(f"An error occurred: {error}")
return error
def create_coursework(service, course_id):
"""Creates and returns a sample coursework."""
try:
coursework = {
"title": "Romeo and Juliet analysis.",
"description": """Write a paper arguing that Romeo and Juliet were
time travelers from the future.""",
"workType": "ASSIGNMENT",
"state": "PUBLISHED",
}
coursework = service.courses().courseWork().create(
courseId=course_id, body=coursework).execute()
return coursework
except HttpError as error:
print(f"An error occurred: {error}")
return error
現在更新 main.py，擷取剛才所測試測試類別的 course_id
已建立新的作業範例，然後擷取作業的
coursework_id:
if __name__ == '__main__':
service = build_authenticated_service(YOUR_API_KEY)
course = get_latest_course(service)
course_id = course.get("id")
course_name = course.get("name")
print(f"'{course_name}' course ID: {course_id}")
coursework = create_coursework(service, course_id)
coursework_id = coursework.get("id")
print(f"Assignment created with ID {coursework_id}")
#TODO(developer): Save the printed course and coursework IDs.
儲存 course_id 和 coursework_id。所有評分量表都必須使用這些評分量表
作業。
您現在可以在 Classroom 取得「CourseWork」範例。
圖 2. 查看 Classroom 中的作業範例。
建立評分量表
現在可以開始管理評分量表。
您可以在 CourseWork 上建立評分量表，並在其中加入含有以下內容的 Create 呼叫
完整評分量表物件，其中省略條件與等級的 ID 屬性
(這些是在建立時產生的)。
在 main.py 中新增下列函式：
def create_rubric(service, course_id, coursework_id):
"""Creates an example rubric on a coursework."""
try:
body = {
"criteria": [
{
"title": "Argument",
"description": "How well structured your argument is.",
"levels": [
{"title": "Convincing",
"description": "A compelling case is made.", "points": 30},
{"title": "Passable",
"description": "Missing some evidence.", "points": 20},
{"title": "Needs Work",
"description": "Not enough strong evidence..", "points": 0},
]
},
{
"title": "Spelling",
"description": "How well you spelled all the words.",
"levels": [
{"title": "Perfect",
"description": "No mistakes.", "points": 20},
{"title": "Great",
"description": "A mistake or two.", "points": 15},
{"title": "Needs Work",
"description": "Many mistakes.", "points": 5},
]
},
{
"title": "Grammar",
"description": "How grammatically correct your sentences are.",
"levels": [
{"title": "Perfect",
"description": "No mistakes.", "points": 20},
{"title": "Great",
"description": "A mistake or two.", "points": 15},
{"title": "Needs Work",
"description": "Many mistakes.", "points": 5},
]
},
]
}
rubric = service.courses().courseWork().rubrics().create(
courseId=course_id, courseWorkId=coursework_id, body=body,
# Specify the preview version. Rubrics CRUD capabilities are
# supported in V1_20231110_PREVIEW and later.
previewVersion="V1_20231110_PREVIEW"
).execute()
print(f"Rubric created with ID {rubric.get('id')}")
return rubric
except HttpError as error:
print(f"An error occurred: {error}")
return error
接著更新並執行 main.py，即可使用 Course 建立評分量表範例
和前 CourseWork 個 ID：
if __name__ == '__main__':
service = build_authenticated_service(YOUR_API_KEY)
rubric = create_rubric(service, YOUR_COURSE_ID, YOUR_COURSEWORK_ID)
print(json.dumps(rubric, indent=4))
使用評分量表的注意事項：
- Classroom 使用者介面會反映相關標準和等級順序。
- 得分等級 (含有
points屬性的項目) 必須依點排序 按遞增或遞減順序排列 (無法隨機排序)。 - 老師可以重新排列標準和評分等級 (但無法重新評分) 並變更資料在資料中的順序。
請參閱限制，進一步瞭解評分量表結構的注意事項。
返回使用者介面，您應該會看到作業的評分量表。
圖 3. 查看 Classroom 作業的評分量表範例。
閱讀評分量表
一份作業最多只能有一個評分量表，因此 List 看起來可能會像這樣
可能不符合直覺，不過如果您尚未取得評分量表 ID 也很有幫助。如果有
沒有與 CourseWork 相關聯的評分量表，List 回應空白。
在 main.py 中新增下列函式：
def get_rubric(service, course_id, coursework_id):
"""
Get the rubric on a coursework. There can only be at most one.
Returns null if there is no rubric.
"""
try:
response = service.courses().courseWork().rubrics().list(
courseId=course_id, courseWorkId=coursework_id,
# Specify the preview version. Rubrics CRUD capabilities are
# supported in V1_20231110_PREVIEW and later.
previewVersion="V1_20231110_PREVIEW"
).execute()
rubrics = response.get("rubrics", [])
if not rubrics:
print("No rubric found for this assignment.")
return
rubric = rubrics[0]
return rubric
except HttpError as error:
print(f"An error occurred: {error}")
return error
更新並執行 main.py，擷取您新增的評分量表：
if __name__ == '__main__':
service = build_authenticated_service(YOUR_API_KEY)
rubric = get_rubric(service, YOUR_COURSE_ID, YOUR_COURSEWORK_ID)
print(json.dumps(rubric, indent=4))
#TODO(developer): Save the printed rubric ID.
請記下評分量表中的 id 屬性，以供後續步驟使用。
您必須有評分量表 ID，Get 才能正常運作。在函式中使用 Get
可能看起來像這樣：
def get_rubric(service, course_id, coursework_id, rubric_id):
"""
Get the rubric on a coursework. There can only be at most one.
Returns a 404 if there is no rubric.
"""
try:
rubric = service.courses().courseWork().rubrics().get(
courseId=course_id,
courseWorkId=coursework_id,
id=rubric_id,
# Specify the preview version. Rubrics CRUD capabilities are
# supported in V1_20231110_PREVIEW and later.
previewVersion="V1_20231110_PREVIEW"
).execute()
return rubric
except HttpError as error:
print(f"An error occurred: {error}")
return error
如果沒有評分量表，此實作會傳回 404。
更新評分量表
評分量表的更新是透過 Patch 呼叫完成。由於結構複雜
更新必須使用「讀取 - 修改 - 寫入」模式，
整個 criteria 屬性都會被取代。
更新規則如下：
- 系統會考慮沒有 ID 新增的條件或等級 新增。
- 系統會考慮之前「缺少」的條件或等級 刪除。
- 系統會考慮已有 ID 但經過修改的資料的條件或層級 編輯。未修改的屬性會保持原樣。
- 透過新的或不明 ID 提供的條件或層級時，則視為適用 錯誤。
- 系統會將新條件和等級的順序視為新的 UI 順序 (同時遵循上述限制)。
新增用於更新評分量表的函式：
def update_rubric(service, course_id, coursework_id, rubric_id, body):
"""
Updates the rubric on a coursework.
"""
try:
rubric = service.courses().courseWork().rubrics().patch(
courseId=course_id,
courseWorkId=coursework_id,
id=rubric_id,
body=body,
updateMask='criteria',
# Specify the preview version. Rubrics CRUD capabilities are
# supported in V1_20231110_PREVIEW and later.
previewVersion="V1_20231110_PREVIEW"
).execute()
return rubric
except HttpError as error:
print(f"An error occurred: {error}")
return error
在這個範例中，criteria 欄位指定的修改方式為
updateMask。
接著修改 main.py，為上述的每次更新進行變更
規則：
if __name__ == '__main__':
service = build_authenticated_service(YOUR_API_KEY)
# Get the latest rubric.
rubric = get_rubric(service, YOUR_COURSE_ID, YOUR_COURSEWORK_ID)
criteria = rubric.get("criteria")
"""
The "criteria" property should look like this:
[
{
"id": "NkEyMdMyMzM2Nxkw",
"title": "Argument",
"description": "How well structured your argument is.",
"levels": [
{
"id": "NkEyMdMyMzM2Nxkx",
"title": "Convincing",
"description": "A compelling case is made.",
"points": 30
},
{
"id": "NkEyMdMyMzM2Nxky",
"title": "Passable",
"description": "Missing some evidence.",
"points": 20
},
{
"id": "NkEyMdMyMzM2Nxkz",
"title": "Needs Work",
"description": "Not enough strong evidence..",
"points": 0
}
]
},
{
"id": "NkEyMdMyMzM2Nxk0",
"title": "Spelling",
"description": "How well you spelled all the words.",
"levels": [...]
},
{
"id": "NkEyMdMyMzM2Nxk4",
"title": "Grammar",
"description": "How grammatically correct your sentences are.",
"levels": [...]
}
]
"""
# Make edits. This example will make one of each type of change.
# Add a new level to the first criteria. Levels must remain sorted by
# points.
new_level = {
"title": "Profound",
"description": "Truly unique insight.",
"points": 50
}
criteria[0]["levels"].insert(0, new_level)
# Remove the last criteria.
del criteria[-1]
# Update the criteria titles with numeric prefixes.
for index, criterion in enumerate(criteria):
criterion["title"] = f"{index}: {criterion['title']}"
# Resort the levels from descending to ascending points.
for criterion in criteria:
criterion["levels"].sort(key=lambda level: level["points"])
# Update the rubric with a patch call.
new_rubric = update_rubric(
service, YOUR_COURSE_ID, YOUR_COURSEWORK_ID, YOUR_RUBRIC_ID, rubric)
print(json.dumps(new_rubric, indent=4))
現在老師就能在 Classroom 中反映這些變更。
圖 4. 查看已更新的評分量表。
查看經評分量表評分的作業
目前無法使用 API 的評分量表批改學生繳交的作業，但 使用評分量表完成評分後，您就能查看評分量表成績 也別忘了善加利用 Classroom UI
以學生身分在 Classroom UI 中完成並繳交作業範例。 然後以老師身分手動使用評分量表批改作業。
圖 5.老師在評分期間查看評分量表。
使用評分量表進行評分的學生繳交作業有兩項
屬性：draftRubricGrades 和 assignedRubricGrades，代表
老師在草稿和指派評分期間選擇的分數和等級
狀態。
此外，相關評分量表的學生繳交作業中會含有rubricId
] 欄位。這代表了與下列項目相關的最新評分量表
如果老師刪除並重新建立 CourseWork 資源，這個值可能會有所變更
。
您可以使用現有的 studentSubmissions.Get 和
studentSubmissions.List 方法，以便查看已評分的作業。
將下列函式加入 main.py 以列出學生繳交的內容：
def get_latest_submission(service, course_id, coursework_id):
"""Retrieves the last submission for an assignment."""
try:
response = service.courses().courseWork().studentSubmissions().list(
courseId = course_id,
courseWorkId = coursework_id,
pageSize=1,
# Specify the preview version. Rubrics CRUD capabilities are
# supported in V1_20231110_PREVIEW and later.
previewVersion="V1_20231110_PREVIEW"
).execute()
submissions = response.get("studentSubmissions", [])
if not submissions:
print(
"""No submissions found. Did you remember to turn in and grade
the assignment in the UI?""")
return
submission = submissions[0]
return submission
except HttpError as error:
print(f"An error occurred: {error}")
return error
接著，更新並執行 main.py，即可查看繳交成績。
if __name__ == '__main__':
service = build_authenticated_service(YOUR_API_KEY)
submission = get_latest_submission(
service, YOUR_COURSE_ID, YOUR_COURSEWORK_ID)
print(json.dumps(submission, indent=4))
draftRubricGrades 和 assignedRubricGrades 包含：
- 相應評分量表標準的
criterionId。 - 老師指派給各項準則的
points。可能來自 但老師也可能覆寫這個設定 - 為各項條件選擇的等級
levelId。如果老師沒有 選擇等級，但仍為該條件指定分數 。
這些清單只包含教師
所選等級或設定分數舉例來說，如果老師選擇
在評分期間與一項條件互動時，draftRubricGrades和
即使評分量表擁有多個項目，assignedRubricGrades 也只會有一個項目
標準。
刪除評分量表
您可以透過標準 Delete 要求刪除評分量表。以下程式碼
顯示完整性的函式範例
，您無法刪除目前的評分量表：
def delete_rubric(service, course_id, coursework_id, rubric_id):
"""Deletes the rubric on a coursework."""
try:
service.courses().courseWork().rubrics().delete(
courseId=course_id,
courseWorkId=coursework_id,
id=rubric_id,
# Specify the preview version. Rubrics CRUD capabilities are
# supported in V1_20231110_PREVIEW and later.
previewVersion="V1_20231110_PREVIEW"
).execute()
except HttpError as error:
print(f"An error occurred: {error}")
return error
匯出及匯入評分量表
評分量表可以手動匯出至 Google 方便老師重複使用的試算表。
除了在程式碼中指定評分量表條件以外，您也可以建立和
如要從這些匯出的工作表中更新評分量表，請指定
評分量表主體中的 sourceSpreadsheetId，而不是 criteria：
def create_rubric_from_sheet(service, course_id, coursework_id, sheet_id):
"""Creates an example rubric on a coursework."""
try:
body = {
"sourceSpreadsheetId": sheet_id
}
rubric = service.courses().courseWork().rubrics().create(
courseId=course_id, courseWorkId=coursework_id, body=body,
# Specify the preview version. Rubrics CRUD capabilities are
# supported in V1_20231110_PREVIEW and later.
previewVersion="V1_20231110_PREVIEW"
).execute()
print(f"Rubric created with ID {rubric.get('id')}")
return rubric
except HttpError as error:
print(f"An error occurred: {error}")
return error
意見回饋
如有任何問題或想提供意見，歡迎分享意見回饋。