rubric là một mẫu mà giáo viên có thể sử dụng khi chấm điểm học viên
nội dung gửi. API lớp học cho phép bạn hành động thay mặt cho
giáo viên để quản lý các tiêu chí chấm điểm này.
Hình 1. Khung hiển thị tiêu chí chấm điểm mẫu cho một bài tập trong Lớp học.
Hướng dẫn này giải thích các khái niệm và chức năng cơ bản của API Tiêu chí. Xem để tìm hiểu về các khái niệm chung trong Trung tâm trợ giúp, cấu trúc của tiêu chí chấm điểm và cách tiêu chí chấm điểm quá trình chấm điểm được thực hiện trong giao diện người dùng Lớp học.
Điều kiện tiên quyết
Hướng dẫn này giả định bạn có:
- Python 3.8.6 trở lên
- Công cụ quản lý gói pip
- Một dự án trên Google Cloud.
- Tài khoản Google Workspace for Education có Google Lớp học bật.
- Lớp học kiểm tra có ít nhất một tài khoản học viên kiểm thử. Nếu bạn không có mà bạn có thể dùng để kiểm tra, tạo một bản đồ trong giao diện người dùng và thêm học viên thử nghiệm.
Cấp thông tin đăng nhập cho ứng dụng dành cho máy tính
Để xác thực là người dùng cuối và truy cập vào dữ liệu người dùng trong ứng dụng của bạn, bạn cần phải tạo một hoặc nhiều Mã ứng dụng khách OAuth 2.0. Mã ứng dụng khách được dùng để xác định một ứng dụng vào máy chủ OAuth của Google. Nếu ứng dụng của bạn chạy trên nhiều nền tảng, bạn phải tạo một mã ứng dụng khách riêng cho từng nền tảng.
- Chuyển đến trang Thông tin xác thực của Google Cloud trong bảng điều khiển Google Cloud.
- Nhấp vào Tạo thông tin xác thực > Mã ứng dụng OAuth.
- Nhấp vào Loại ứng dụng > Ứng dụng dành cho máy tính.
- Trong trường Tên, nhập tên cho thông tin đăng nhập. Tên này chỉ hiển thị trong bảng điều khiển Google Cloud. Ví dụ: "Ứng dụng xem trước tiêu chí chấm điểm".
- Nhấp vào Tạo. Màn hình OAuth do ứng dụng tạo xuất hiện, cho thấy Mã ứng dụng khách và Mật khẩu ứng dụng khách.
- Nhấp vào Tải JSON xuống, sau đó nhấp vào OK. Thông tin đăng nhập mới tạo sẽ xuất hiện trong Mã ứng dụng khách OAuth 2.0.
- Lưu tệp JSON đã tải xuống dưới dạng
credentials.jsonrồi chuyển tệp đó sang thư mục đang làm việc của bạn. - Nhấp vào Tạo thông tin xác thực > Khoá API và ghi lại khoá API.
Xem bài viết Tạo thông tin xác thực truy cập để tìm hiểu thêm.
Định cấu hình phạm vi của OAuth
Tuỳ thuộc vào phạm vi OAuth hiện tại của dự án, bạn có thể cần định cấu hình phạm vi bổ sung.
- Chuyển đến màn hình xin phép bằng OAuth.
- Nhấp vào Chỉnh sửa ứng dụng > Lưu và tiếp tục để chuyển đến màn hình Phạm vi.
- Nhấp vào Add or Remove Scopes (Thêm hoặc xoá phạm vi).
- Hãy thêm các phạm vi sau nếu bạn chưa có:
https://www.googleapis.com/auth/classroom.coursework.studentshttps://www.googleapis.com/auth/classroom.courses
- Sau đó Nhấp vào Cập nhật > Lưu và tiếp tục > Lưu và tiếp tục > Quay lại Trang tổng quan.
Xem bài viết Định cấu hình màn hình xin phép bằng OAuth để tìm hiểu khác.
Phạm vi classroom.coursework.students cấp quyền đọc và ghi vào
tiêu chí chấm điểm (cùng với quyền truy cập vào CourseWork) và phạm vi classroom.courses
cho phép đọc và viết khoá học.
Các phạm vi bắt buộc đối với một phương thức cụ thể được liệt kê trong tài liệu tham khảo
cho phương thức đó. Xem courses.courseWork.rubrics.create phạm vi uỷ quyền
làm ví dụ. Bạn có thể xem tất cả các phạm vi Lớp học trong phần Phạm vi OAuth 2.0 cho Google
API. Tiêu chí chấm điểm không được đề cập ở đây vì API này vẫn đang ở dạng bản xem trước.
Định cấu hình mẫu
Trong thư mục đang hoạt động, hãy cài đặt thư viện ứng dụng của Google cho Python:
pip install --upgrade google-api-python-client google-auth-httplib2 google-auth-oauthlib
Tạo một tệp có tên là main.py để tạo thư viện ứng dụng và cho phép
bằng cách sử dụng khoá API của bạn thay cho 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)
Chạy tập lệnh bằng python main.py. Bạn sẽ được nhắc đăng nhập và
đồng ý với phạm vi OAuth.
Tạo bài tập
Tiêu chí chấm điểm được liên kết với một bài tập hoặc CourseWork và chỉ
có ý nghĩa trong ngữ cảnh của CourseWork đó. Chỉ có thể tạo tiêu chí chấm điểm bằng
dự án Google Cloud đã tạo mục CourseWork mẹ. Đối với các mục đích
trong hướng dẫn này, hãy tạo một bài tập CourseWork mới có tập lệnh.
Thêm đoạn mã sau vào 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
Bây giờ, hãy cập nhật main.py để truy xuất course_id của lớp kiểm thử mà bạn vừa
tạo, tạo bài tập mẫu mới và truy xuất bài tập
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.
Lưu course_id và coursework_id. Cần có những nguyên tắc này cho tất cả tiêu chí chấm điểm CRUD
các toán tử.
Bây giờ, bạn sẽ có một CourseWork mẫu trong Lớp học.
Hình 2. Khung hiển thị một bài tập mẫu trong Lớp học.
Tạo tiêu chí chấm điểm
Bây giờ, bạn đã sẵn sàng bắt đầu quản lý các tiêu chí chấm điểm.
Bạn có thể tạo tiêu chí chấm điểm trên CourseWork bằng lệnh gọi Create chứa
đối tượng tiêu chí chấm điểm đầy đủ, trong đó thuộc tính mã nhận dạng cho các tiêu chí và cấp bị bỏ qua
(những thông tin này được tạo khi tạo).
Thêm hàm sau vào 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
Sau đó, hãy cập nhật và chạy main.py để tạo tiêu chí chấm điểm mẫu bằng cách sử dụng Course
và CourseWork mã trước đó:
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))
Một số điểm về cách trình bày tiêu chí chấm điểm:
- Thứ tự tiêu chí và cấp độ được phản ánh trong giao diện người dùng của Lớp học.
- Các cấp được tính điểm (những cấp có thuộc tính
points), phải được sắp xếp theo điểm theo thứ tự tăng dần hoặc giảm dần (không thể sắp xếp ngẫu nhiên). - Giáo viên có thể sắp xếp lại tiêu chí và mức điểm (nhưng không bị trừ điểm) cấp) trong giao diện người dùng và điều đó làm thay đổi thứ tự của chúng trong dữ liệu.
Xem các giới hạn để biết thêm cảnh báo về cấu trúc tiêu chí chấm điểm.
Quay lại giao diện người dùng, bạn sẽ thấy tiêu chí chấm điểm trên bài tập.
Hình 3. Khung hiển thị tiêu chí chấm điểm mẫu cho một bài tập trong Lớp học.
Đọc hướng dẫn
Bạn có thể đọc tiêu chí chấm điểm bằng phương thức List và Get tiêu chuẩn.
Một bài tập có thể có tối đa một tiêu chí chấm điểm, vì vậy, List có thể xuất hiện
khó hiểu nhưng sẽ hữu ích nếu bạn chưa có ID tiêu chí chấm điểm. Nếu có
không có tiêu chí chấm điểm được liên kết với CourseWork, phản hồi List trống.
Thêm hàm sau vào 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
Cập nhật và chạy main.py để tìm nạp tiêu chí chấm điểm bạn đã thêm:
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.
Hãy lưu ý thuộc tính id trong tiêu chí chấm điểm cho các bước sau.
Get sẽ hoạt động hiệu quả khi bạn có mã tiêu chí chấm điểm. Sử dụng Get trong hàm
thay vào đó có thể có dạng như sau:
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
Cách triển khai này sẽ trả về lỗi 404 nếu không có tiêu chí chấm điểm.
Cập nhật tiêu chí chấm điểm
Quá trình cập nhật tiêu chí chấm điểm được thực hiện thông qua các lệnh gọi Patch. Do cấu trúc phức tạp
của một tiêu chí chấm điểm, phải cập nhật bằng mẫu đọc-sửa đổi-ghi, trong đó
toàn bộ thuộc tính criteria được thay thế.
Các quy tắc cập nhật như sau:
- Tiêu chí hoặc cấp độ được thêm mà không có mã nhận dạng sẽ được cân nhắc bổ sung.
- Các tiêu chí hoặc cấp độ bị thiếu so với trước đó sẽ được xem xét xoá.
- Tiêu chí hoặc cấp độ có mã nhận dạng hiện có nhưng dữ liệu đã sửa đổi sẽ được xem xét chỉnh sửa. Các thuộc tính chưa sửa đổi sẽ giữ nguyên.
- Các tiêu chí hoặc cấp độ được cung cấp kèm theo mã nhận dạng mới hoặc không xác định sẽ được xem xét lỗi.
- Thứ tự của các tiêu chí và cấp mới được coi là thứ tự mới của giao diện người dùng (cùng với các giới hạn nêu trên).
Thêm một hàm để cập nhật tiêu chí chấm điểm:
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
Trong ví dụ này, trường criteria được chỉ định để sửa đổi bằng
updateMask.
Sau đó, hãy sửa đổi main.py để thực hiện thay đổi cho từng nội dung cập nhật nêu trên
quy tắc:
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))
Lúc này, các thay đổi này sẽ được áp dụng cho giáo viên trong Lớp học.
Hình 4. Giao diện tiêu chí chấm điểm mới cập nhật.
Xem bài tập được chấm điểm theo tiêu chí chấm điểm
Hiện tại, bạn không thể chấm điểm bài tập đã nộp của học viên theo tiêu chí chấm điểm của API, nhưng bạn có thể đọc điểm theo tiêu chí chấm điểm đối với những bài tập đã được chấm điểm theo tiêu chí chấm điểm trong giao diện người dùng Lớp học.
Trong giao diện người dùng của Lớp học, khi là học viên, hãy hoàn thành và gửi bài tập mẫu. Sau đó, giáo viên có thể chấm điểm bài tập theo cách thủ công theo bộ tiêu chí chấm điểm.
Hình 5. Chế độ xem của giáo viên về tiêu chí chấm điểm trong khi chấm điểm.
Bài tập mà học viên gửi đã được chấm điểm theo tiêu chí chấm điểm sẽ có hai
thuộc tính: draftRubricGrades và assignedRubricGrades, đại diện cho
điểm và cấp độ do giáo viên chọn trong quá trình chấm điểm bản nháp và được giao
các trạng thái tương ứng.
Ngoài ra, bài tập mà học viên nộp theo một tiêu chí chấm điểm liên kết sẽ có rubricId
trước khi chấm điểm. Tiêu chí này đại diện cho tiêu chí chấm điểm mới nhất liên quan đến
CourseWork và giá trị này có thể thay đổi nếu giáo viên xoá và tạo lại một
tiêu chí chấm điểm.
Bạn có thể sử dụng studentSubmissions.Get hiện có và
Phương thức studentSubmissions.List để xem bài tập đã chấm điểm.
Thêm hàm sau vào main.py để liệt kê những bài học viên đã nộp:
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
Sau đó, hãy cập nhật và chạy main.py để xem điểm nộp bài.
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 và assignedRubricGrades chứa:
criterionIdcủa các tiêu chí chấm điểm tương ứng.pointsmà giáo viên chỉ định cho mỗi tiêu chí. Đây có thể là từ cấp độ đã chọn nhưng giáo viên cũng có thể đã ghi đè cấp độ này.levelIdcủa cấp độ được chọn cho mỗi tiêu chí. Nếu giáo viên không chọn một cấp nhưng vẫn được gán điểm cho tiêu chí, trường này không tồn tại.
Các danh sách này chỉ chứa các mục nhập cho các tiêu chí mà giáo viên
đã chọn một cấp hoặc đặt điểm. Ví dụ: nếu giáo viên chọn chỉ
tương tác với một tiêu chí trong quá trình chấm điểm, draftRubricGrades và
assignedRubricGrades sẽ chỉ có một mục, ngay cả khi tiêu chí chấm điểm có nhiều mục
tiêu chí.
Xóa tiêu chí chấm điểm
Bạn có thể xoá tiêu chí chấm điểm bằng một yêu cầu Delete tiêu chuẩn. Mã sau đây
cho thấy một hàm ví dụ về tính hoàn chỉnh, nhưng vì tính năng chấm điểm đã
đã bắt đầu, bạn không thể xoá tiêu chí chấm điểm hiện tại:
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
Xuất và nhập tiêu chí chấm điểm
Bạn có thể xuất các tiêu chí chấm điểm sang Google theo cách thủ công Bảng tính để giáo viên sử dụng lại.
Ngoài việc chỉ định tiêu chí chấm điểm trong mã, bạn có thể tạo và
cập nhật tiêu chí chấm điểm từ các trang tính đã xuất này bằng cách chỉ định
sourceSpreadsheetId trong phần nội dung tiêu chí chấm điểm thay vì 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
Phản hồi
Nếu bạn gặp vấn đề hoặc có ý kiến đóng góp, hãy chia sẻ ý kiến phản hồi.