rubric الگویی است که معلمان می توانند هنگام نمره دادن به مطالب ارسالی دانش آموزان از آن استفاده کنند. Classroom API به شما امکان میدهد از طرف معلم برای مدیریت این روبریکها و همچنین خواندن نمرات عنوان در مورد ارسالی دانشآموزان اقدام کنید.
شکل 1. نمای یک روبریک نمونه در یک تکلیف کلاس درس.
این راهنما مفاهیم اساسی و عملکرد Rubrics API را توضیح می دهد. این مقالههای مرکز راهنمایی را ببینید تا در مورد ساختار کلی یک روبریک و نحوه درجهبندی روبریک در رابط کاربری کلاس درس بیاموزید.
پیش نیازها
این راهنما فرض می کند که شما موارد زیر را دارید:
- پایتون 3.8.6 یا بالاتر
- ابزار مدیریت بسته پیپ
- یک پروژه Google Cloud .
- یک حساب Google Workspace for Education با Google Classroom فعال و مجوز Google Workspace for Education Plus به آن اختصاص داده شده است. اگر ندارید، میتوانید یک حساب آزمایشی توسعهدهنده ارتقا یافته درخواست کنید .
- یک کلاس آزمایشی با حداقل یک حساب دانشجوی آزمایشی. اگر کلاس Classroom ندارید که بتوانید از آن برای آزمایش استفاده کنید، یکی در رابط کاربری ایجاد کنید و یک دانشآموز آزمایشی اضافه کنید .
مجوز اعتبار برای یک برنامه دسکتاپ
برای احراز هویت به عنوان کاربر نهایی و دسترسی به داده های کاربر در برنامه خود، باید یک یا چند شناسه مشتری OAuth 2.0 ایجاد کنید. شناسه مشتری برای شناسایی یک برنامه واحد در سرورهای OAuth Google استفاده می شود. اگر برنامه شما روی چندین پلتفرم اجرا می شود، باید برای هر پلتفرم یک شناسه مشتری جداگانه ایجاد کنید.
- به صفحه Google Cloud Credentials در کنسول Google Cloud بروید.
- روی ایجاد اعتبارنامه > شناسه مشتری OAuth کلیک کنید.
- روی نوع برنامه > برنامه دسکتاپ کلیک کنید.
- در قسمت نام ، نامی را برای اعتبارنامه تایپ کنید. این نام فقط در کنسول Google Cloud نشان داده می شود. به عنوان مثال، "مشتری Rubrics".
- روی ایجاد کلیک کنید. صفحه ایجاد شده توسط سرویس گیرنده OAuth ظاهر می شود که شناسه مشتری و راز مشتری جدید شما را نشان می دهد.
- روی Download JSON کلیک کنید و سپس بر روی OK کلیک کنید. اعتبار جدید ایجاد شده در شناسه های مشتری OAuth 2.0 ظاهر می شود.
- فایل JSON دانلود شده را به عنوان
credentials.jsonذخیره کنید و فایل را به دایرکتوری کاری خود منتقل کنید. - روی Create Credentials > API Key کلیک کنید و کلید API را یادداشت کنید.
برای اطلاعات بیشتر به ایجاد اعتبار دسترسی مراجعه کنید.
دامنه های OAuth را پیکربندی کنید
بسته به محدوده های OAuth موجود پروژه شما، ممکن است نیاز به پیکربندی دامنه های افزودنی داشته باشید.
- به صفحه رضایت OAuth بروید.
- برای رفتن به صفحه Scopes روی Edit App > Save و Continue کلیک کنید.
- روی Add or Remove Scopes کلیک کنید.
- اگر دامنه های زیر را ندارید اضافه کنید:
-
https://www.googleapis.com/auth/classroom.coursework.students -
https://www.googleapis.com/auth/classroom.courses
-
- سپس روی Update > Save and Continue > Save and Continue > Back to Dashboard کلیک کنید.
برای اطلاعات بیشتر به پیکربندی صفحه رضایت OAuth مراجعه کنید.
دامنه classroom.coursework.students امکان دسترسی خواندن و نوشتن به روبریک ها را فراهم می کند (همراه با دسترسی به CourseWork )، و دامنه classroom.courses امکان خواندن و نوشتن دوره ها را فراهم می کند.
دامنه مورد نیاز برای یک روش معین در مستندات مرجع برای روش ذکر شده است. به عنوان نمونه به courses.courseWork.rubrics.create حوزه های مجوز مراجعه کنید. میتوانید همه حوزههای Classroom را در OAuth 2.0 Scopes for Google API مشاهده کنید.
نمونه را پیکربندی کنید
در فهرست کاری خود، کتابخانه مشتری Google را برای پایتون نصب کنید:
pip install --upgrade google-api-python-client google-auth-httplib2 google-auth-oauthlib
با استفاده از کلید API به جای YOUR_API_KEY ، فایلی به نام main.py ایجاد کنید که کتابخانه سرویس گیرنده را بسازد و به کاربر اجازه دهد:
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 معنادار است. روبریک ها را فقط می توان توسط پروژه Google Cloud ایجاد کرد که مورد اصلی CourseWork را ایجاد کرد . برای اهداف این راهنما، یک تکلیف 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 را ذخیره کنید. اینها برای همه عملیاتهای CRUD مورد نیاز هستند.
اکنون باید یک نمونه CourseWork در Classroom داشته باشید.
شکل 2. نمای یک تکلیف نمونه در کلاس درس.
واجد شرایط بودن کاربر را بررسی کنید
ایجاد و بهروزرسانی روبریکها مستلزم آن است که هم کاربر درخواستکننده و هم صاحب دوره مربوطه، مجوز Google Workspace for Education Plus به آنها اختصاص داده شده باشد. Classroom از یک نقطه پایانی واجد شرایط بودن کاربر پشتیبانی می کند تا توسعه دهندگان را قادر می سازد قابلیت هایی را که کاربر به آنها دسترسی دارد تعیین کنند.
main.py بهروزرسانی و اجرا کنید تا تأیید کنید که حساب آزمایشی شما به قابلیت روبریکها دسترسی دارد:
if __name__ == '__main__':
service = build_authenticated_service(YOUR_API_KEY)
capability = service.userProfiles().checkUserCapability(
userId='me',
# Specify the preview version. checkUserCapability is
# supported in V1_20240930_PREVIEW and later.
previewVersion="V1_20240930_PREVIEW",
capability="CREATE_RUBRIC").execute()
if not capability.get('allowed'):
print('User ineligible for rubrics creation.')
# TODO(developer): in a production app, this signal could be used to
# proactively hide any rubrics related features from users or encourage
# them to upgrade to the appropriate license.
else:
print('User eligible for rubrics creation.')
یک روبریک ایجاد کنید
اکنون شما آماده شروع مدیریت روبریک ها هستید.
یک روبریک را می توان در یک 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
).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 قبلی، روبریک نمونه ایجاد کنید:
if __name__ == '__main__':
service = build_authenticated_service(YOUR_API_KEY)
capability = service.userProfiles().checkUserCapability(
userId='me',
# Specify the preview version. checkUserCapability is
# supported in V1_20240930_PREVIEW and later.
previewVersion="V1_20240930_PREVIEW",
capability="CREATE_RUBRIC").execute()
if not capability.get('allowed'):
print('User ineligible for rubrics creation.')
# TODO(developer): in a production app, this signal could be used to
# proactively hide any rubrics related features from users or encourage
# them to upgrade to the appropriate license.
else:
rubric = create_rubric(service, YOUR_COURSE_ID, YOUR_COURSEWORK_ID)
print(json.dumps(rubric, indent=4))
چند نکته در مورد نمایش روبریک:
- معیار و ترتیب سطح در رابط کاربری کلاس درس منعکس شده است.
- سطوح امتیازدهی شده (آنهایی که دارای ویژگی
pointsهستند)، باید بر اساس امتیاز به ترتیب صعودی یا نزولی مرتب شوند (نمی توان آنها را به طور تصادفی مرتب کرد). - معلمان می توانند معیارها و سطوح امتیازدهی شده (اما نه سطوح بدون امتیاز) را در UI مرتب کنند و این ترتیب آنها را در داده ها تغییر می دهد.
برای اخطارهای بیشتر در مورد ساختار روبریک ها، محدودیت ها را ببینید.
در UI، باید روبریک مربوط به تکلیف را ببینید.
شکل 3. نمای یک روبریک نمونه در یک تکلیف کلاس درس.
یک روبریک بخوانید
روبریک ها را می توان با متدهای استاندارد list() و get() خواند.
حداکثر می تواند یک روبریک در یک انتساب وجود داشته باشد، بنابراین list() ممکن است غیر قابل درک به نظر برسد، اما اگر قبلاً شناسه روبریک را نداشته باشید، مفید است. اگر هیچ روبریکی مرتبط با 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
).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 در روبریک توجه کنید.
هنگامی که شناسه روبریک دارید، 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
).execute()
return rubric
except HttpError as error:
print(f"An error occurred: {error}")
return error
اگر روبریکی وجود نداشته باشد، این پیاده سازی 404 را برمی گرداند.
یک روبریک را به روز کنید
به روز رسانی یک روبریک با فراخوانی patch() انجام می شود. به دلیل ساختار پیچیده یک روبریک، به روز رسانی ها باید با یک الگوی خواندن، تغییر، نوشتن انجام شود، جایی که کل ویژگی criteria جایگزین می شود.
قوانین به روز رسانی به شرح زیر است:
- ضوابط یا سطوح اضافه شده بدون شناسه به عنوان موارد اضافه در نظر گرفته می شوند.
- معیارها یا سطوحی که از قبل حذف شده اند حذف محسوب می شوند.
- معیارها یا سطوح با شناسه موجود اما دادههای اصلاحشده، ویرایش محسوب میشوند. ویژگی های اصلاح نشده به همان صورت باقی می مانند.
- معیارها یا سطوح ارائه شده با شناسه های جدید یا ناشناخته به عنوان خطا در نظر گرفته می شوند.
- ترتیب معیارها و سطوح جدید به عنوان ترتیب 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'
).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)
capability = service.userProfiles().checkUserCapability(
userId='me',
# Specify the preview version. checkUserCapability is
# supported in V1_20240930_PREVIEW and later.
previewVersion="V1_20240930_PREVIEW",
capability="CREATE_RUBRIC").execute()
if not capability.get('allowed'):
print('User ineligible for rubrics creation.')
# TODO(developer): in a production app, this signal could be used to
# proactively hide any rubrics related features from users or encourage
# them to upgrade to the appropriate license.
else:
# 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. نمای معلم از روبریک در حین درجه بندی.
StudentSubmissions که با یک روبریک درجهبندی شدهاند، دو ویژگی جدید دارند: draftRubricGrades و assignedRubricGrades که به ترتیب نشاندهنده امتیازات و سطوح انتخاب شده توسط معلم در طول پیشنویس و وضعیتهای نمرهدهی اختصاصیافته است.
شما می توانید از متدهای 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
).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
).execute()
except HttpError as error:
print(f"An error occurred: {error}")
return error
روبریک صادرات و واردات
روبریک ها را می توان به صورت دستی برای استفاده مجدد توسط معلمان به Google Spreadsheets صادر کرد .
علاوه بر تعیین معیارهای روبریک در کد، امکان ایجاد و بهروزرسانی روبریکها از این برگههای صادر شده با تعیین 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
).execute()
print(f"Rubric created with ID {rubric.get('id')}")
return rubric
except HttpError as error:
print(f"An error occurred: {error}")
return error