rubric است که معلمان می توانند هنگام نمره دادن به مطالب ارسالی دانش آموزان از آن استفاده کنند. Classroom API به شما امکان می‌دهد از طرف معلم برای مدیریت این روبریک‌ها اقدام کنید.
شکل 1. نمای یک روبریک نمونه در یک تکلیف کلاس درس.
این راهنما مفاهیم اساسی و عملکرد Rubrics API را توضیح می دهد. این مقاله‌های مرکز راهنمایی را ببینید تا در مورد ساختار کلی یک روبریک و نحوه درجه‌بندی روبریک در رابط کاربری کلاس درس بیاموزید.
پیش نیازها
این راهنما فرض می کند که شما موارد زیر را دارید:
- پایتون 3.8.6 یا بالاتر
- ابزار مدیریت بسته پیپ
- یک پروژه Google Cloud .
- حساب Google Workspace for Education با Google Classroom فعال است .
- یک کلاس آزمایشی با حداقل یک حساب دانشجوی آزمایشی. اگر کلاس 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 مشاهده کنید. Rubrics در اینجا ذکر نشده است زیرا 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. نمای یک تکلیف نمونه در کلاس درس.
یک روبریک ایجاد کنید
اکنون شما آماده شروع مدیریت روبریک ها هستید.
یک روبریک را می توان در یک 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 قبلی، روبریک نمونه ایجاد کنید:
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))
چند نکته در مورد نمایش روبریک:
- معیار و ترتیب سطح در رابط کاربری کلاس درس منعکس شده است.
- سطوح امتیازدهی شده (آنهایی که دارای ویژگی
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,
# 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 در روبریک توجه کنید.
وقتی شناسه روبریک را دارید Get به خوبی کار می کند. در عوض استفاده از تابع Get in ممکن است به شکل زیر باشد:
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 جایگزین می شود.
قوانین به روز رسانی به شرح زیر است:
- ضوابط یا سطوح اضافه شده بدون شناسه به عنوان موارد اضافه در نظر گرفته می شوند.
- معیارها یا سطوحی که از قبل حذف شده اند حذف محسوب می شوند.
- معیارها یا سطوح با شناسه موجود اما داده‌های اصلاح‌شده، ویرایش محسوب می‌شوند. ویژگی های اصلاح نشده به همان صورت باقی می مانند.
- معیارها یا سطوح ارائه شده با شناسه های جدید یا ناشناخته به عنوان خطا در نظر گرفته می شوند.
- ترتیب معیارها و سطوح جدید به عنوان ترتیب 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 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,
# 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
بازخورد
اگر مشکلی پیدا کردید یا ورودی دارید، بازخورد خود را به اشتراک بگذارید.