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

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

التحقّق من أهلية مستخدم لإعداد فترات التقييم

يُسمح بطلبات إلى نقطة النهاية userProfiles.checkUserCapability نيابةً عن أي مشرف أو معلّم. استخدِم هذا الإعداد لتحديد ما إذا كان بإمكان المستخدم تعديل فترات وضع الدرجات.

المتطلبات الأساسية

يقدّم هذا الدليل أمثلة على الرموز البرمجية بلغة Python، ويفترض أنّك تستوفي الشروط التالية:

  • مشروع 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 ستحتاج إلى بيانات اعتماد معلّم لإنشاء "المهام الدراسية" أو تعديلها. لا يمكن للمشرفين إنشاء أو تعديل "الواجب الدراسي" إذا لم يكونوا معلّمين في الدورة التدريبية.

إدارة مورد GradingPeriodSettings

يتضمّن المرجع GradingPeriodSettings قائمة بعناصر GradingPeriods فردية وحقل منطقي باسم applyToExistingCoursework.

يُرجى التأكّد من أنّ كل فرد GradingPeriods في القائمة يستوفي المتطلبات التالية:

  • العنوان وتاريخ البدء وتاريخ الانتهاء: يجب أن تتضمّن كل فترة تقييم عنوانًا وتاريخ بدء وتاريخ انتهاء.
  • عنوان فريد: يجب أن يكون لكل فترة وضع درجات عنوان فريد لا يتطابق مع أي فترات وضع درجات أخرى في الدورة التدريبية.
  • تواريخ غير متداخلة: يجب ألا يتضمّن كل فترة تقييم تواريخ بدء أو انتهاء تتداخل مع أي فترات تقييم أخرى في الدورة التدريبية.
  • الترتيب الزمني: يجب إدراج فترات وضع الدرجات بترتيب زمني استنادًا إلى تاريخَي البدء والانتهاء.

سيتم تعيين معرّف من خلال Classroom API لكل فترة تقييم عند إنشائها.

قيمة applyToExistingCoursework المنطقية هي إعداد دائم يتيح لك تنظيم CourseWork التي تم إنشاؤها سابقًا في فترات التقييم بدون الحاجة إلى إجراء طلب منفصل من واجهة برمجة التطبيقات لتعديل gradingPeriodId لكل CourseWork. إذا تم ضبطها على True، سيضبط Classroom تلقائيًا gradingPeriodId على جميع "المهام الدراسية" الحالية إذا كان courseWork.dueDate يقع ضمن تاريخَي البدء والانتهاء لفترة تقييم حالية. إذا لم يتم تحديد تاريخ استحقاق في "المادة الدراسية"، سيستخدم Classroom courseWork.scheduledTime. إذا لم يكن أي من الحقلين متوفّرًا أو لم يكن هناك تطابق ضمن تاريخَي البدء والانتهاء لفترة وضع الدرجات الحالية، لن يتم ربط "الواجب الدراسي" بأي فترة لوضع الدرجات.

تحديد ما إذا كان بإمكان المستخدم تعديل إعدادات فترة التقييم في إحدى الدورات التدريبية

توفّر Classroom API نقطة النهاية userProfiles.checkUserCapability لمساعدتك في تحديد ما إذا كان بإمكان المستخدم إرسال طلبات إلى نقطة النهاية UpdateGradingPeriodSettings بشكل استباقي.

Python

def check_grading_periods_update_capability(classroom_service, course_id):
    """Checks whether a user is able to create and modify grading periods in a course."""
    try:
        capability = classroom_service.userProfiles().checkUserCapability(
          userId="me",
          capability="UPDATE_GRADING_PERIOD_SETTINGS",
           # Required while the checkUserCapability method is available in the Developer Preview Program.
          previewVersion="V1_20240930_PREVIEW"
        ).execute()

        # Retrieve the `allowed` boolean from the response.
        if capability.get("allowed"):
          print("User is allowed to update grading period settings in the course.")
        else:
          print("User is not allowed to update grading period settings in the course.")
    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_service, 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_service.courses().updateGradingPeriodSettings(
          courseId=course_id,
          updateMask='gradingPeriods,applyToExistingCoursework',
          body=body
        ).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_service, course_id):
    """Read grading periods settings in a course."""
    try:
        gradingPeriodSettings = classroom_service.courses().getGradingPeriodSettings(
          courseId=course_id).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. يُرجى العِلم أنّه لن تتم إزالة أي فترات وضع درجات تم تطبيقها سابقًا على "الواجب الدراسي" الحالي. في المثال السابق، تم تطبيق الفترتين "الفصل الدراسي الأول" و"الفصل الدراسي الثاني" على "الواجب الدراسي" الحالي، ولن تتم إزالتهما من "الواجب الدراسي" إذا تم ضبط applyToExistingCoursework على "خطأ" في الطلبات اللاحقة.

def add_grading_period(classroom_service, 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_service.courses().updateGradingPeriodSettings(
          courseId=course_id, body=body, updateMask='gradingPeriods,applyToExistingCoursework').execute()
        return gradingPeriodSettings

    except HttpError as error:
        # Handle errors as appropriate for your application.
        print(f"An error occurred: {error}")
        return error

تذكيرات مفيدة بشأن الحقل المنطقي applyToExistingCoursework

يُرجى العِلم أنّه يتم applyToExistingCourseworkتخزين القيمة المنطقية applyToExistingCoursework، ما يعني أنّه إذا تم ضبط القيمة المنطقية على True في طلب سابق لواجهة برمجة التطبيقات ولم يتم تغييرها، سيتم تطبيق التعديلات اللاحقة على فترات التقييم على CourseWork الحالية.

يُرجى العِلم أنّه في حال تغيير هذه القيمة المنطقية من True إلى False في طلب إلى UpdateGradingPeriodSettings، لن يتم تطبيق التغييرات الجديدة التي تجريها على GradingPeriodSettings على "المهام الدراسية" الحالية. لن تتم إزالة أي معلومات عن فترة التقييم تم تطبيقها على CourseWork في طلبات سابقة من واجهة برمجة التطبيقات عندما تم ضبط القيمة المنطقية على True. من الطرق المفيدة للتفكير في إعدادات القيمة المنطقية هذه أنّها تتيح ربط CourseWork الحالية بفترات التقييم التي تم إعدادها، ولكنّها لا تتيح إزالة عمليات الربط الحالية بين CourseWork وفترات التقييم التي تم إعدادها.

في حال حذف عنوان فترة التقييم أو تغييره، سيتم تطبيق هذه التغييرات على جميع "المهام الدراسية" الحالية، بغض النظر عن قيمة السمة المنطقية applyToExistingCoursework.

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

لتعديل بعض البيانات المرتبطة بفترة تقييم حالية، أدرِج معرّف فترة التقييم الحالية في القائمة مع البيانات المعدَّلة.

Python

في هذا المثال، سيتم تعديل تاريخ انتهاء فترة التقييم "الصيف". سيتم ضبط الحقل "applyToExistingCoursework" على True. ملاحظة: سيؤدي ضبط قيمة هذا الخيار المنطقي على True إلى تطبيق جميع الفترات المحدّدة للتقييم على "الواجب الدراسي" الحالي. في طلب واجهة برمجة التطبيقات السابق، تم ضبط القيمة المنطقية على False حتى لا يتم تطبيق فترة التقييم "الصيف" على "الواجبات الدراسية" الحالية. بعد ضبط هذا الحقل المنطقي على True، سيتم تطبيق فترة التقييم "الصيف" على جميع "المهام الدراسية" الحالية التي تتطابق معها.

def update_existing_grading_period(classroom_service, 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_service.courses().updateGradingPeriodSettings(
          courseId=course_id, body=body, updateMask='gradingPeriods,applyToExistingCoursework').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_service, 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_service.courses().updateGradingPeriodSettings(
          courseId=course_id, body=body, updateMask='gradingPeriods').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، سيحدّد Classroom قيمة gradingPeriodId استنادًا إلى الحقل scheduledTime. في حال عدم تحديد أي من الحقلين، أو إذا لم يكن هناك تطابق مع النطاق الزمني لفترة التقييم، لن يتم ضبط أي gradingPeriodId في CourseWork.

2. فترة وضع الدرجات المرتبطة المخصّصة

إذا أردت ربط "الواجب الدراسي" بفترة تقييم مختلفة عن الفترة التي تتوافق مع dueDate أو scheduledTime، يمكنك ضبط الحقل gradingPeriodId يدويًا عند إنشاء "الواجب الدراسي" أو تعديله. في حال ضبط gradingPeriodId يدويًا، لن يربط Classroom تلقائيًا فترة وضع الدرجات بالتاريخ.

3- لا يوجد ربط بفترة وضع الدرجات

إذا كنت لا تريد ربط مهمة CourseWork بأي فترة تقييم على الإطلاق، اضبط الحقل gradingPeriodId في طلب CourseWork على سلسلة فارغة (gradingPeriodId: "").

إذا كنت تستخدم لغة البرمجة Go وأردت عدم تحديد فترة تقييم، عليك أيضًا تضمين الحقل ForceSendFields في نص الطلب. باستخدام مكتبة برامج Go، يتم حذف القيم التلقائية من طلبات واجهة برمجة التطبيقات بسبب توفّر علامة الحقل omitempty في جميع الحقول. يتجاوز الحقل ForceSendFields ذلك ويرسل السلسلة الفارغة للإشارة إلى أنّك لا تريد ضبط أي فترة تقييم لهذا الواجب. لمزيد من المعلومات، يمكنك الاطّلاع على مستندات مكتبة برامج Google APIs للغة Go.

انتقال

courseWork := &classroom.CourseWork{
  Title: "Homework questions",
  WorkType: "ASSIGNMENT",
  State: "DRAFT",
  // ...other CourseWork fields...
  GradingPeriodId: "",
  ForceSendFields: []string{"GradingPeriodId"},
}

ماذا يحدث لمعرّف فترة وضع الدرجات إذا تم تعديل تاريخ التسليم؟

إذا كنت تعدّل حقل dueDate في CourseWork وأردت الحفاظ على ارتباط مخصّص أو بدون فترة وضع درجات، عليك تضمين 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_service.courses().courseWork().patch(
  courseId=course_id, id=coursework_id, body=body,
  updateMask='dueDate,dueTime,gradingPeriodId') # include the gradingPeriodId field in the updateMask
.execute()
السابق
ضبط الدرجات وتعديلها
التالي
القيود