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

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

نظرة عامة

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

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

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

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

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

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

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

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

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

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

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

سيساعدك هذا النمط على التأكد من أن عناوين فترات الدرجات الفردية في الدورة التدريبية مميزة ومن عدم وجود تداخل بين تاريخي البدء والانتهاء لفترات وضع الدرجات.

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

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

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