إدارة فترات وضع الدرجات باستخدام Classroom API

يوضّح هذا الدليل كيفية استخدام نقاط نهاية فترات التقييم في Google Classroom API.

نظرة عامة

يتم إنشاء فترات وضع الدرجات لتنظيم الواجبات المنزلية والاختبارات والمشاريع في نطاقات زمنية محدّدة. تتيح Classroom API للمطوّرين قراءة فترات وضع الدرجات في Classroom وتعديلها وإنشائها بالنيابة عن المشرفين والمعلّمين. يمكنك أيضًا استخدام Classroom API لتعيين فترات وضع الدرجات في CourseWork.

تقدّم Classroom API نقطتَي نهاية لقراءة معلومات فترة التقييم وكتابتها في دورة تدريبية:

  • GetGradingPeriodSettings: يتيح لك الاطّلاع على إعدادات فترة وضع الدرجات في أحد الدورات الدراسية.
  • UpdateGradingPeriodSettings: يتيح لك إدارة إعدادات فترة التقييم في أحد البكالوريوس عن طريق إضافة فترات التقييم وتعديلها وحذفها، وتطبيق فترات التقييم التي تم ضبطها على كل أعمال الدورة التدريبية الحالية.

متطلبات الترخيص

تعديل إعدادات فترة وضع الدرجات في دورة تدريبية

لإنشاء فترات وضع الدرجات أو تعديلها أو حذفها في دورة تدريبية باستخدام نقطة النهاية UpdateGradingPeriodSettings، يجب استيفاء الشروط التالية:

قراءة إعدادات فترة وضع الدرجات في دورة دراسية

يمكن لمشرفي النطاقات ومعلّمي الدورات التدريبية قراءة إعدادات ملف تقييم الأداء بغض النظر عن الترخيص الذي تم منحه لهم. ويعني هذا أنّ الطلبات إلى نقطة النهاية 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

إضافة فترة وضع درجات فردية إلى القائمة

يجب إجراء التعديلات على فترة تقييم فردية باتّباع نمط قراءة-تعديل-كتابة. وهذا يعني أنّه عليك تنفيذ ما يلي:

  1. اقرأ قائمة فترات التقييم ضمن مورد GradingPeriodSettings باستخدام نقطة النهاية GetGradingPeriodSettings.
  2. أدخِل التعديلات التي اخترتها على قائمة فترات التقييم.
  3. يُرجى إرسال قائمة فترات وضع الدرجات الجديدة في طلب إلى "UpdateGradingPeriodSettings".

سيساعدك هذا النمط في التأكّد من أنّ عناوين الفترات الفردية للتصحيح في أحد الدورات الدراسية مختلفة وأنّه ما مِن تداخل بين تواريخ بدء الفترات الفردية للتصحيح وتاريخ انتهائها.

يُرجى مراعاة القواعد التالية بشأن تعديل قائمة فترات وضع الدرجات:

  1. تُعتبر فترات التقييم المُضافة إلى القائمة بدون رقم تعريف إضافات.
  2. تُعتبر الفترات الزمنية غير المتوفّرة في القائمة عمليات حذف.
  3. فترات وضع الدرجات التي لها رقم تعريف حالي ولكن البيانات المعدّلة تُعتبر تعديلات. ويتم ترك السمات غير المعدَّلة كما هي.
  4. تُعدّ الفترات الزمنية للتصنيف التي تتضمّن معرّفات جديدة أو غير معروفة أخطاء.

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()