يشرح هذا الدليل كيفية استخدام نقاط نهاية فترات وضع الدرجات في Google Classroom API.
نظرة عامة
يتم إنشاء فترات وضع الدرجات لتنظيم الواجب المنزلي والاختبارات والمشروعات في نطاقات زمنية محددة. تسمح Classroom API للمطوّرين بإنشاء فترات وضع الدرجات وتعديلها وقراءتها في Classroom نيابةً عن المشرفين والمعلّمين. يمكنك أيضًا استخدام Classroom API لتعيين فترات وضع الدرجات في CourseWork.
توفر Classroom API نقطتَي نهاية لقراءة معلومات فترة وضع الدرجات وكتابتها في دورة تدريبية:
GetGradingPeriodSettings
: تتيح لك قراءة إعدادات فترة وضع الدرجات في دورة تدريبية.UpdateGradingPeriodSettings
: تتيح لك إدارة إعدادات فترة وضع الدرجات في دورة تدريبية عن طريق إضافة فترات وضع الدرجات وتعديلها وحذفها وتطبيق فترات وضع الدرجات التي تم ضبطها على جميع CourseWork الحالية.
متطلبات الترخيص
تعديل إعدادات فترة وضع الدرجات في دورة تدريبية
لإنشاء فترات وضع الدرجات أو تعديلها أو حذفها في دورة تدريبية باستخدام نقطة النهاية UpdateGradingPeriodSettings
، يجب استيفاء الشروط التالية:
- تم منح المستخدم الذي يقدّم الطلب ترخيص Google Workspace for Education Plus.
- أن يكون مالك الدورة التدريبية قد تم منحه ترخيص Google Workspace for Education Plus.
قراءة إعدادات فترة وضع الدرجات في دورة تدريبية
يمكن لمشرفي النطاقات ومعلّمي الدورة التدريبية قراءة إعدادات فترة وضع الدرجات
بغض النظر عن الترخيص الذي تم منحه لهم. ويعني هذا أنّ الطلبات إلى نقطة النهاية GetGradingPeriodSettings
مسموح بها نيابةً عن أي مشرف نطاق أو معلّم.
ضبط رقم تعريف لفترة وضع الدرجات في CourseWork
ويمكن لمعلّمي الدورة التدريبية تضمين gradingPeriodId
عند إنشاء
عمل CourseWork أو تعديله باستخدام واجهة برمجة التطبيقات بغض النظر عن الترخيص الذي تم منحه لهم.
التحقّق من أهلية المستخدم لإعداد فترات وضع الدرجات
يتم السماح بالطلبات إلى نقطة النهاية checkGradingPeriodsSetupEligibility
نيابةً عن أي مشرف أو معلّم. استخدم هذا لتحديد ما إذا كان يمكن للمستخدم
تعديل فترات الدرجات في الدورة التدريبية.
المتطلّبات الأساسية
يقدم هذا الدليل أمثلة على التعليمات البرمجية في بايثون، ويفترض أن لديك:
- مشروع على Google Cloud يمكنك إعداد موقع إلكتروني من خلال اتّباع التعليمات الواردة في Python Quickstart.
- تمت إضافة النطاقات التالية إلى شاشة طلب الموافقة المتعلّقة ببروتوكول 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 ستحتاج إلى بيانات اعتماد المعلم لإنشاء أو تعديل CourseWork. لا يمكن للمشرفين إنشاء CourseWork أو تعديله إذا لم يكونوا معلمين في الدورة التدريبية.
إدارة مورد "GradingPeriodSettings
"
يتضمن مورد GradingPeriodSettings
قائمة بـ GradingPeriods
الفردية
وحقلًا منطقيًا يسمى applyToExistingCoursework
.
تمثّل قائمة GradingPeriods
جميع فترات وضع الدرجات الفردية في دورة تدريبية. يجب تحديد عنوان وتاريخ بدء وتاريخ انتهاء لكل فترة تصنيف فردية في القائمة. يجب أن يكون لكل فترة وضع درجات في الدورة عنوان
فريد، ولا يمكن أن تتداخل تواريخ البدء والانتهاء لفترات التقييم المختلفة. سيكون لكل فترة وضع درجات معرّف خاص بها تم تعيينه لواجهة Classroom API.
القيمة المنطقية applyToExistingCoursework
هي إعداد ثابت يتيح لك تنظيم CourseWork الذي تم إنشاؤه مسبقًا في فترات وضع الدرجات بدون الحاجة إلى
إجراء طلب بيانات منفصل من واجهة برمجة التطبيقات لتعديل gradingPeriodId
لكل CourseWork. في حال ضبط القيمة على True
، سيضبط Classroom تلقائيًا السمة gradingPeriodId
في جميع مهام CourseWork الحالية إذا كانت السمة courseWork.dueDate
تقع ضمن تاريخَي البدء والانتهاء لفترة وضع الدرجات الحالية. إذا لم يتم تحديد تاريخ تسليم في CourseWork، سيستخدم Classroom
courseWork.scheduledTime
. إذا لم يتوفر أي حقل أو لم يكن هناك تطابق ضمن تاريخي البدء والانتهاء لفترة وضع الدرجات الحالية،
فلن يتم ربط عمل CourseWork بأي فترة وضع درجات.
تحديد ما إذا كان يمكن للمستخدم تعديل إعدادات فترة وضع الدرجات في دورة تدريبية
بما أنّ إمكانية إنشاء فترات وضع الدرجات وتعديلها في 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
سواء كنت تضيف فترات وضع درجات فردية أو تعدّل فترات وضع الدرجات الحالية أو تحذف فترة وضع الدرجات.
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
. لاحظ أنه لن تتم إزالة أي فترات وضع درجات سبق تطبيقها
على CourseWork الحالية. في المثال السابق،
تم تطبيق فترتَي وضع الدرجات "الفصل 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
. هناك طريقة مفيدة للتفكير في هذا الإعداد المنطقي وهي أنه يدعم ربط CourseWork الحالية بفترات التقييم التي تمت تهيئتها، ولكنه لا يتيح إزالة الارتباطات الحالية بين CourseWork وفترات وضع الدرجات التي تم تكوينها.
في حال حذف أو تغيير عنوان فترة وضع الدرجات، سيتم نشر هذه التغييرات
في جميع مهام CourseWork الحالية، بغض النظر عن إعداد
القيمة المنطقية applyToExistingCoursework
.
تعديل فترة وضع درجات فردية في القائمة
لتعديل بعض البيانات المرتبطة بفترة وضع الدرجات الحالية، قم بتضمين رقم تعريف فترة الدرجات الحالية في القائمة مع البيانات المعدلة.
Python
في هذا المثال، سيتم تعديل تاريخ انتهاء فترة وضع الدرجات "الصيف". سيتمّ ضبط الحقل applyToExistingCoursework
على True
. يُرجى العلم أنّ ضبط هذه القيمة المنطقية على True
سيؤدي إلى تطبيق جميع فترات وضع الدرجات التي تم ضبطها في CourseWork الحالية. في طلب واجهة برمجة التطبيقات السابق، تم ضبط القيمة المنطقية على False
بحيث لم يتم تطبيق فترة وضع الدرجات "الصيف" على
CourseWork الحالية. الآن بعد أن تم ضبط هذا الحقل المنطقي على 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- ربط فترة وضع الدرجات استنادًا إلى التاريخ
عند إنشاء CourseWork، يمكنك السماح لـ Classroom بالتعامل مع
فترة وضع الدرجات نيابةً عنك. للقيام بذلك، احذف الحقل gradingPeriodId
من طلب CourseWork. بعد ذلك، حدِّد الحقلين dueDate
أو scheduledTime
في طلب CourseWork. إذا كانت السمة dueDate
تقع ضمن نطاق زمني حالي لفترة وضع الدرجات، سيضبط Classroom رقم تعريف فترة وضع الدرجات هذه على CourseWork. إذا لم يتم تحديد الحقل dueDate
،
سيحدِّد Classroom السمة gradingPeriodId
استنادًا إلى الحقل
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()