يوضّح هذا الدليل كيفية استخدام نقاط نهاية فترات التقييم في Google Classroom API.
نظرة عامة
يتم إنشاء فترات وضع الدرجات لتنظيم الواجبات المنزلية والاختبارات والمشاريع في نطاقات زمنية محدّدة. تتيح Classroom API للمطوّرين قراءة فترات وضع الدرجات في Classroom وتعديلها وإنشائها بالنيابة عن المشرفين والمعلّمين. يمكنك أيضًا استخدام Classroom API لتعيين فترات وضع الدرجات في CourseWork.
تقدّم Classroom API نقطتَي نهاية لقراءة معلومات فترة التقييم وكتابتها في دورة تدريبية:
GetGradingPeriodSettings
: يتيح لك الاطّلاع على إعدادات فترة وضع الدرجات في أحد الدورات الدراسية.UpdateGradingPeriodSettings
: يتيح لك إدارة إعدادات فترة التقييم في أحد البكالوريوس عن طريق إضافة فترات التقييم وتعديلها وحذفها، وتطبيق فترات التقييم التي تم ضبطها على كل أعمال الدورة التدريبية الحالية.
متطلبات الترخيص
تعديل إعدادات فترة وضع الدرجات في دورة تدريبية
لإنشاء فترات وضع الدرجات أو تعديلها أو حذفها في دورة تدريبية باستخدام نقطة النهاية UpdateGradingPeriodSettings
، يجب استيفاء الشروط التالية:
- أن يكون لدى المستخدم الذي يقدّم الطلب ترخيص Google Workspace for Education Plus ممنوحًا له
- أن يكون لدى مالك الدورة التدريبية ترخيص Google Workspace for Education Plus
قراءة إعدادات فترة وضع الدرجات في دورة دراسية
يمكن لمشرفي النطاقات ومعلّمي الدورات التدريبية قراءة إعدادات ملف تقييم الأداء
بغض النظر عن الترخيص الذي تم منحه لهم. ويعني هذا أنّ الطلبات إلى نقطة النهاية GetGradingPeriodSettings
مسموح بها نيابةً عن أي مشرف نطاق أو معلّم.
ضبط رقم تعريف فترة وضع الدرجات في CourseWork
يمكن لمعلّمي الدورة التدريبية تضمين gradingPeriodId
عند إنشاء أو تعديل
CourseWork باستخدام واجهة برمجة التطبيقات بغض النظر عن الترخيص الذي تم منحه لهم.
التحقّق من أهلية مستخدم لإعداد فترات التقييم
يتم السماح بالطلبات إلى نقطة النهاية checkGradingPeriodsSetupEligibility
نيابةً عن أي مشرف أو معلّم. استخدِم هذا الخيار لتحديد ما إذا كان بإمكان
المستخدم تعديل فترات التقييم في دورة تدريبية.
المتطلبات الأساسية
يقدم هذا الدليل أمثلة على التعليمات البرمجية في بايثون، ويفترض أن لديك:
- مشروع على Google Cloud يمكنك إعداد حساب باتّباع التعليمات الواردة في مقالة البدء السريع باستخدام Python.
- تمت إضافة النطاقات التالية إلى شاشة طلب موافقة OAuth لمشروعك:
https://www.googleapis.com/auth/classroom.courses
https://www.googleapis.com/auth/classroom.coursework.students
- رقم تعريف الدورة التدريبية التي يجب تعديل فترات وضع الدرجات فيها يجب أن يكون لدى مالك الدورة التدريبية ترخيص Google Workspace for Education Plus.
- الوصول إلى بيانات اعتماد المعلّم أو المشرف باستخدام ترخيص Google Workspace for Education Plus ستحتاج إلى بيانات اعتماد معلّم لإنشاء "واجب دراسي" أو تعديله. لا يمكن للمشرفين إنشاء أو تعديل assignments إذا لم يكونوا معلّمين في الدورة التدريبية.
إدارة المورد GradingPeriodSettings
يتضمّن مورد GradingPeriodSettings
قائمة بعناصر
GradingPeriods
فردية وحقلًا منطقيًا يُسمى applyToExistingCoursework
.
تمثّل قائمة GradingPeriods
جميع الفترات الفردية لتقييم الأداء في
دورة تدريبية. يجب تحديد عنوان وتاريخ البدء وتاريخ الانتهاء لكل فترة وضع درجات فردية في القائمة. يجب أن يكون لكل فترة وضع درجات في الدورة التدريبية
عنوان فريد، ولا يمكن أن تتزامن تواريخ بدء وانتهاء فترات وضع الدرجات المختلفة. سيكون لكل فترة تقييم معرّف خاص بها تحدّده واجهة برمجة التطبيقات Classroom API.
القيمة المنطقية applyToExistingCoursework
هي إعداد دائم يتيح لك
تنظيم "أعمال الدورة الدراسية" التي تم إنشاؤها سابقًا في فترات التقييم بدون الحاجة إلى
إجراء طلب منفصل لواجهة برمجة التطبيقات لتعديل gradingPeriodId
لكل "عمل دورة دراسية". إذا
تم ضبطه على True
، سيضبط Classroom تلقائيًاgradingPeriodId
على جميع أعمال الدورة التدريبية الحالية إذا كانcourseWork.dueDate
يقع ضمن تاريخَي بدء و
انتهاء فترة تقييم حالية. إذا لم يتم تحديد تاريخ تسليم في CourseWork، سيستخدم Classroom
courseWork.scheduledTime
. إذا لم يكن أيّ من الحقلين متوفّرًا أو
لم يكن هناك تطابق بين تاريخَي البدء والانتهاء لفترة تقييم حالية، لن يكون
العمل الدراسي مرتبطًا بأيّ فترة تقييم.
تحديد ما إذا كان يمكن للمستخدم تعديل إعدادات فترة وضع الدرجات في دورة تدريبية
بما أنّ إمكانية إنشاء فترات وضع الدرجات وتعديلها في Classroom لا تتوفّر إلا للمستخدمين الذين لديهم ترخيص معيّن،
توفّر Classroom API
نقطة النهاية checkGradingPeriodsSetupEligibility
لمساعدتك في تحديد ما إذا كان بإمكان المستخدم تقديم طلبات إلى نقطة النهاية
UpdateGradingPeriodSettings
بشكل استباقي.
Python
def check_grading_period_setup_eligibility(classroom, course_id):
"""Checks whether a user is able to create and modify grading periods in a course."""
try:
grading_period_eligibility_response = classroom.courses().checkGradingPeriodsSetupEligibility(
courseId=course_id, previewVersion="V1_20240401_PREVIEW").execute()
# Retrieve the isGradingPeriodsSetupEligible boolean from the response.
# If the boolean is `True`, the user is able to modify grading period settings in the course.
is_grading_periods_eligible = grading_period_eligibility_response.get("isGradingPeriodsSetupEligible")
return is_grading_periods_eligible
except HttpError as error:
# Handle errors as appropriate for your application.
print(f"An error occurred: {error}")
return error
إضافة فترات وضع الدرجات
بعد التأكّد من أنّ المستخدم لديه الترخيص المطلوب لتعديل
إعدادات فترة التقييم في إحدى الدورات التدريبية، يمكنك بدء إرسال الطلبات إلى نقطة نهاية
UpdateGradingPeriodSettings
. يتم إجراء أي تعديلات على موارد
GradingPeriodSettings
باستخدام نقطة نهاية
UpdateGradingPeriodSettings
سواء كنت تضيف فترات تقييم individual
أو تعدّل فترات تقييم حالية أو تحذف فترة تقييم.
Python
في المثال التالي، تم تعديل المورد gradingPeriodSettings
لتضمين فترتين للتصنيف. يتم ضبط القيمة المنطقية applyToExistingCoursework
على True
، ما سيؤدي إلى تعديل gradingPeriodId
في أي من مهام CourseWork الحالية التي تقع بين تاريخ بدء وتاريخ انتهاء فترة وضع الدرجات. يُرجى العلم
أنّ updateMask
يتضمّن كلا الحقلين. احفظ معرّفات الفترات الفردية
للتصحيح بعد عرضها في الردّ. ستحتاج إلى استخدام أرقام التعريف
هذه لتحديث فترات الدرجات إذا لزم الأمر.
def create_grading_periods(classroom, course_id):
"""
Create grading periods in a course and apply the grading periods
to existing courseWork.
"""
try:
body = {
"gradingPeriods": [
{
"title": "First Semester",
"start_date": {
"day": 1,
"month": 9,
"year": 2023
},
"end_date": {
"day": 15,
"month": 12,
"year": 2023
}
},
{
"title": "Second Semester",
"start_date": {
"day": 15,
"month": 1,
"year": 2024
},
"end_date": {
"day": 31,
"month": 5,
"year": 2024
}
}
],
"applyToExistingCoursework": True
}
gradingPeriodSettingsResponse = classroom.courses().updateGradingPeriodSettings(
courseId=course_id,
updateMask='gradingPeriods,applyToExistingCoursework',
body=body,
previewVersion="V1_20240401_PREVIEW"
).execute();
print(f"Grading period settings updated.")
return gradingPeriodSettingsResponse
except HttpError as error:
# Handle errors as appropriate for your application.
print(f"An error occurred: {error}")
return error
قراءة إعدادات فترة وضع الدرجات
يتم قراءة GradingPeriodSettings
باستخدام نقطة النهاية GetGradingPeriodSettings
.
يمكن لأي مستخدم، بغض النظر عن الترخيص، قراءة إعدادات فترات التقييم في الدورة التدريبية.
Python
def get_grading_period_settings(classroom, course_id):
"""Read grading periods settings in a course."""
try:
gradingPeriodSettings = classroom.courses().getGradingPeriodSettings(
courseId=course_id, previewVersion="V1_20240401_PREVIEW").execute()
return gradingPeriodSettings
except HttpError as error:
# Handle errors as appropriate for your application.
print(f"An error occurred: {error}")
return error
إضافة فترة وضع درجات فردية إلى القائمة
يجب إجراء التعديلات على فترة تقييم فردية باتّباع نمط قراءة-تعديل-كتابة. وهذا يعني أنّه عليك تنفيذ ما يلي:
- اقرأ قائمة فترات التقييم ضمن مورد
GradingPeriodSettings
باستخدام نقطة النهايةGetGradingPeriodSettings
. - أدخِل التعديلات التي اخترتها على قائمة فترات التقييم.
- يُرجى إرسال قائمة فترات وضع الدرجات الجديدة في طلب إلى
"
UpdateGradingPeriodSettings
".
سيساعدك هذا النمط في التأكّد من أنّ عناوين الفترات الفردية للتصحيح في أحد الدورات الدراسية مختلفة وأنّه ما مِن تداخل بين تواريخ بدء الفترات الفردية للتصحيح وتاريخ انتهائها.
يُرجى مراعاة القواعد التالية بشأن تعديل قائمة فترات وضع الدرجات:
- تُعتبر فترات التقييم المُضافة إلى القائمة بدون رقم تعريف إضافات.
- تُعتبر الفترات الزمنية غير المتوفّرة في القائمة عمليات حذف.
- فترات وضع الدرجات التي لها رقم تعريف حالي ولكن البيانات المعدّلة تُعتبر تعديلات. ويتم ترك السمات غير المعدَّلة كما هي.
- تُعدّ الفترات الزمنية للتصنيف التي تتضمّن معرّفات جديدة أو غير معروفة أخطاء.
Python
تستند التعليمة البرمجية التالية إلى المثال الوارد في هذا الدليل. تم إنشاء فترة وضع درجات
جديدة بعنوان "الصيف". تم ضبط القيمة الحقيقية/الكاذبة applyToExistingCoursework
على False
في نص الطلب.
لإجراء ذلك، تتم قراءة GradingPeriodSettings
الحالية، وتتم إضافة فترة تقييم
جديدة إلى القائمة، ويتم ضبط القيمة المنطقيةapplyToExistingCoursework
على False
. يُرجى العلم أنّه لن تتم إزالة أي فترات تقييم سبق أن
تم تطبيقها على "أعمال الدورة الدراسية" الحالية. في المثال السابق،
تم تطبيق فترتَي وضع الدرجات "الفصل 1" و"الفصل 2" مسبقًا على
عمل CourseWork الحالي ولن تتم إزالتهما من CourseWork في حال
ضبط applyToExistingCoursework
على "خطأ" في الطلبات اللاحقة.
def add_grading_period(classroom, course_id):
"""
A new grading period is added to the list, but it is not applied to existing courseWork.
"""
try:
# Use the `GetGradingPeriodSettings` endpoint to retrieve the existing
# grading period IDs. You will need to include these IDs in the request
# body to make sure existing grading periods aren't deleted.
body = {
"gradingPeriods": [
{
# Specify the ID to make sure the grading period is not deleted.
"id": "FIRST_SEMESTER_GRADING_PERIOD_ID",
"title": "First Semester",
"start_date": {
"day": 1,
"month": 9,
"year": 2023
},
"end_date": {
"day": 15,
"month": 12,
"year": 2023
}
},
{
# Specify the ID to make sure the grading period is not deleted.
"id": "SECOND_SEMESTER_GRADING_PERIOD_ID",
"title": "Second Semester",
"start_date": {
"day": 15,
"month": 1,
"year": 2024
},
"end_date": {
"day": 31,
"month": 5,
"year": 2024
}
},
{
# Does not include an ID because this grading period is an addition.
"title": "Summer",
"start_date": {
"day": 1,
"month": 6,
"year": 2024
},
"end_date": {
"day": 31,
"month": 8,
"year": 2024
}
}
],
"applyToExistingCoursework": False
}
gradingPeriodSettings = classroom.courses().updateGradingPeriodSettings(
courseId=course_id, body=body, updateMask='gradingPeriods,applyToExistingCoursework',
previewVersion="V1_20240401_PREVIEW").execute()
return gradingPeriodSettings
except HttpError as error:
# Handle errors as appropriate for your application.
print(f"An error occurred: {error}")
return error
مؤشرات مفيدة حول حقل applyToExistingCoursework
المنطقي
من المهم تذكُّر أنّ القيمة المنطقية applyToExistingCoursework
مستمرة، ما يعني أنّه إذا تم ضبط القيمة المنطقية على True
في طلب بيانات سابق من واجهة برمجة التطبيقات
ولم يتم تغييرها، سيتم تطبيق التعديلات اللاحقة على فترات وضع الدرجات على
CourseWork الحالية.
يُرجى العِلم أنّه في حال تغيير هذه القيمة المنطقية من True
إلى False
في طلب
إلى UpdateGradingPeriodSettings
، لن يتم تطبيق التغييرات الجديدة التي تجريها على
GradingPeriodSettings
فقط على CourseWork الحالية. لن تتم إزالة أي معلومات متعلقة بفترة التقييم
التي تم تطبيقها على CourseWork في طلبات البيانات السابقة من واجهة برمجة التطبيقات عندما تم ضبط القيمة الحقيقية/الكاذبة
على True
. من الطرق المفيدة للتفكير في هذا الإعداد المنطقي
أنّه يتيح ربط "أعمال الدورة التدريبية" الحالية بفترات التقييم
المُعدّة، ولكنّه لا يتيح إزالة الربط
الحالي بين "أعمال الدورة التدريبية" وفترات التقييم المُعدّة.
في حال حذف عنوان فترة تقييم أو تغييره، سيتم
نشر هذه التغييرات في جميع أعمال الدورة التدريبية الحالية، بغض النظر عن إعداد القيمة المنطقية
applyToExistingCoursework
.
تعديل فترة وضع درجات فردية في القائمة
لتعديل بعض البيانات المرتبطة بفترة تقييم حالية، أدرِج رقم تعريف فترة التقييم الحالية في القائمة التي تتضمّن البيانات المعدَّلة.
Python
في هذا المثال، سيتم تعديل تاريخ انتهاء فترة التقييم "الصيف". سيتم ضبط الحقل applyToExistingCoursework
على True
. يُرجى العلم
أنّ ضبط هذه القيمة المنطقية على True
سيؤدي إلى تطبيق جميع فترات التقييم
المُعدّة على "أعمال الدورة الدراسية" الحالية. في طلب واجهة برمجة التطبيقات السابق، تمَّ
ضبط القيمة المنطقية على False
لكي لا يتم تطبيق فترة التقييم "الصيف" على
المهام الدراسية الحالية. الآن بعد أن تم ضبط هذا الحقل المنطقي على True
، سيتم تطبيق فترة وضع الدرجات "الصيف" على جميع CourseWork الحالية المطابقة.
def update_existing_grading_period(classroom, course_id):
"""
An existing grading period is updated.
"""
try:
# Use the `GetGradingPeriodSettings` endpoint to retrieve the existing
# grading period IDs. You will need to include these IDs in the request
# body to make sure existing grading periods aren't deleted.
body = {
"gradingPeriods": [
{
"id": "FIRST_SEMESTER_GRADING_PERIOD_ID",
"title": "First Semester",
"start_date": {
"day": 1,
"month": 9,
"year": 2023
},
"end_date": {
"day": 15,
"month": 12,
"year": 2023
}
},
{
"id": "SECOND_SEMESTER_GRADING_PERIOD_ID",
"title": "Second Semester",
"start_date": {
"day": 15,
"month": 1,
"year": 2024
},
"end_date": {
"day": 31,
"month": 5,
"year": 2024
}
},
{
# The end date for this grading period will be modified from August 31, 2024 to September 10, 2024.
# Include the grading period ID in the request along with the new data.
"id": "SUMMER_GRADING_PERIOD_ID",
"title": "Summer",
"start_date": {
"day": 1,
"month": 6,
"year": 2024
},
"end_date": {
"day": 10,
"month": 9,
"year": 2024
}
}
],
"applyToExistingCoursework": True
}
gradingPeriodSettings = classroom.courses().updateGradingPeriodSettings(
courseId=course_id, body=body, updateMask='gradingPeriods,applyToExistingCoursework',
previewVersion="V1_20240401_PREVIEW").execute()
return gradingPeriodSettings
except HttpError as error:
# Handle errors as appropriate for your application.
print(f"An error occurred: {error}")
return error
حذف فترة وضع درجات فردية
لحذف فترة وضع الدرجات، احذفها من القائمة. يُرجى العلم أنّه في حال حذف
فترة وضع الدرجات، سيتم أيضًا حذف أي إشارة إلى فترة وضع الدرجات في
CourseWork بغض النظر عن إعداد applyToExistingCoursework
.
Python
لمواصلة المثال الوارد في هذا الدليل، احذف فترة التقييم "الصيف" .
def delete_grading_period(classroom, course_id):
"""
An existing grading period is deleted.
"""
try:
body = {
"gradingPeriods": [
{
"id": "FIRST_SEMESTER_GRADING_PERIOD_ID",
"title": "First Semester",
"start_date": {
"day": 1,
"month": 9,
"year": 2023
},
"end_date": {
"day": 15,
"month": 12,
"year": 2023
}
},
{
"id": "SECOND_SEMESTER_GRADING_PERIOD_ID",
"title": "Second Semester",
"start_date": {
"day": 15,
"month": 1,
"year": 2024
},
"end_date": {
"day": 31,
"month": 5,
"year": 2024
}
}
]
}
gradingPeriodSettings = classroom.courses().updateGradingPeriodSettings(
courseId=course_id, body=body, updateMask='gradingPeriods',
previewVersion="V1_20240401_PREVIEW").execute()
return gradingPeriodSettings
except HttpError as error:
# Handle errors as appropriate for your application.
print(f"An error occurred: {error}")
return error
إدارة حقل gradingPeriodId
في CourseWork
يتضمّن مرجع CourseWork حقل gradingPeriodId
. يمكنك استخدام نقاط نهاية
CourseWork لقراءة وكتابة فترة التقييم المرتبطة بأحد مشاريع
CourseWork. هناك ثلاث طرق لإدارة هذا الربط:
- الربط التلقائي لفترة وضع الدرجات بالتاريخ
- فترة وضع درجات مرتبطة ومخصّصة
- ما مِن ربط بفترة وضع الدرجات
1. ربط فترة وضع الدرجات بالتاريخ
عند إنشاء "عمل المقرر الدراسي"، يمكنك السماح لخدمة Classroom بمعالجة عملية ربط
فترة التقييم نيابةً عنك. لإجراء ذلك، يجب حذف الحقل gradingPeriodId
من طلب CourseWork. بعد ذلك، حدِّد الحقلين dueDate
أو scheduledTime
في طلب CourseWork. إذا كان dueDate
يقع في نطاق زمني حالي
للفترة لوضع الدرجات، سيضبط Classroom رقم تعريف
هذه الفترة لوضع الدرجات في CourseWork. في حال عدم تحديد الحقل dueDate
، تحدِّد Google ClassroomgradingPeriodId
استنادًا إلى الحقل
scheduledTime
. إذا لم يتم تحديد أيّ من الحقلَين، أو لم يتطابق النطاق الزمني لفترة وضع الدرجات، لن يتم ضبط gradingPeriodId
في CourseWork.
2. فترة وضع درجات مرتبطة مخصّصة
إذا كنت تريد ربط CourseWork بفترة تقييم مختلفة
عن الفترة التي تتوافق مع dueDate
أو scheduledTime
، يمكنك تحديد الحقل gradingPeriodId
يدويًا
عند إنشاء CourseWork أو تعديله. إذا أعددتgradingPeriodId
يدويًا، لن تُجري Classroom عملية الربط التلقائي لفترة وضع الدرجات استنادًا إلى التاريخ.
3- ما مِن ارتباط بفترة وضع الدرجات.
إذا كنت لا تريد ربط CourseWork بأي فترة وضع درجات على الإطلاق،
يمكنك ضبط الحقل gradingPeriodId
في طلب CourseWork على سلسلة
فارغة (gradingPeriodId
: ""
).
ماذا يحدث لمعرّف فترة التقييم في حال تعديل تاريخ الاستحقاق؟
إذا كنت تعدّل حقل CourseWork dueDate
وتريد الاحتفاظ بربط
مخصّص أو عدم ربط فترة التقييم، عليك تضمين dueDate
و
gradingPeriodId
في updateMask ونص الطلب. سيؤدي ذلك إلى توجيه
Classroom إلى عدم إلغاء gradingPeriodId
باستخدام فترة تقييم
تطابق مع dueDate
الجديدة.
Python
body = {
"dueDate": {
"month": 6,
"day": 10,
"year": 2024
},
"dueTime": {
"hours": 7
},
"gradingPeriodId": "<INSERT-GRADING-PERIOD-ID-OR-EMPTY-STRING>"
}
courseWork = classroom.courses().courseWork().patch(
courseId=course_id, id=coursework_id, body=body,
updateMask='dueDate,dueTime,gradingPeriodId', # include the gradingPeriodId field in the updateMask
previewVersion="V1_20240401_PREVIEW").execute()