دوره های درجه بندی را با استفاده از API Classroom مدیریت کنید

این راهنما نحوه استفاده از نقاط پایانی دوره های درجه بندی را در Google Classroom API توضیح می دهد.

نمای کلی

دوره‌های درجه‌بندی برای سازماندهی تکالیف، آزمون‌ها و پروژه‌ها در محدوده‌های تاریخی خاص ایجاد می‌شوند. Classroom API به توسعه دهندگان این امکان را می دهد که از طرف مدیران و معلمان دوره های رتبه بندی را در Classroom ایجاد، تغییر دهند و بخوانند. همچنین می‌توانید از Classroom API برای تنظیم دوره‌های نمره‌دهی در CourseWork استفاده کنید.

Classroom API دو نقطه پایانی برای خواندن و نوشتن اطلاعات دوره نمره دهی در یک دوره ارائه می دهد:

  • GetGradingPeriodSettings : به شما امکان می دهد تنظیمات دوره نمره دهی را در یک دوره مطالعه کنید.
  • UpdateGradingPeriodSettings : به شما امکان می دهد تنظیمات دوره های درجه بندی را در یک دوره با افزودن، اصلاح و حذف دوره های درجه بندی و اعمال دوره های درجه بندی پیکربندی شده برای همه CourseWork موجود مدیریت کنید.

الزامات صدور مجوز

تنظیمات دوره نمره دهی را در یک دوره تغییر دهید

برای ایجاد، تغییر یا حذف دوره های نمره دهی در یک دوره با استفاده از نقطه پایانی UpdateGradingPeriodSettings ، شرایط زیر باید رعایت شود:

تنظیمات دوره نمره دهی را در یک دوره بخوانید

مدیران دامنه و معلمان یک دوره می توانند تنظیمات دوره درجه بندی را بدون توجه به مجوزی که به آنها اختصاص داده شده است بخوانند . این بدان معناست که درخواست‌ها به نقطه پایانی GetGradingPeriodSettings از طرف هر مدیر یا معلم دامنه مجاز است.

یک شناسه دوره نمره گذاری در CourseWork تنظیم کنید

معلمان یک دوره می‌توانند هنگام ایجاد یا به‌روزرسانی CourseWork با استفاده از API بدون در نظر گرفتن مجوزی که به آنها اختصاص داده شده است، gradingPeriodId وارد کنند.

واجد شرایط بودن یک کاربر برای تنظیم دوره های درجه بندی را بررسی کنید

درخواست به نقطه پایانی checkGradingPeriodsSetupEligibility از طرف هر مدیر یا معلمی مجاز است. از این برای تعیین اینکه آیا کاربر می تواند دوره های درجه بندی در یک دوره را تغییر دهد یا خیر، استفاده کنید.

پیش نیازها

این راهنما نمونه هایی از کد را در پایتون ارائه می دهد و فرض می کند که شما دارید:

  • یک پروژه Google Cloud. می‌توانید یکی از دستورالعمل‌های موجود در راه‌اندازی سریع پایتون را تنظیم کنید.
  • دامنه های زیر را به صفحه رضایت 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 قبلا ایجاد شده را در دوره های درجه بندی سازماندهی کنید بدون اینکه نیازی به ایجاد یک فراخوان API جداگانه برای تغییر gradingPeriodId برای هر CourseWork باشد. اگر روی True تنظیم شود، اگر courseWork.dueDate در تاریخ شروع و پایان دوره نمره‌دهی موجود باشد، Classroom به‌طور خودکار gradingPeriodId در تمام CourseWork موجود تنظیم می‌کند. اگر تاریخ سررسیدی در CourseWork تعیین نشده باشد، Classroom از courseWork.scheduledTime استفاده خواهد کرد. اگر هیچ یک از فیلدها وجود نداشته باشد یا در تاریخ شروع و پایان یک دوره رتبه بندی موجود مطابقت نداشته باشد، CourseWork با هیچ دوره درجه بندی مرتبط نخواهد بود.

تعیین کنید که آیا کاربر می تواند تنظیمات دوره درجه بندی را در یک دوره تغییر دهد یا خیر

از آنجایی که امکان ایجاد و تغییر دوره‌های درجه‌بندی در Classroom فقط برای کاربران دارای مجوز خاص در دسترس است، API Classroom نقطه پایانی checkGradingPeriodsSetupEligibility ارائه می‌کند تا به شما کمک کند به طور فعال تعیین کنید که آیا کاربر می‌تواند به نقطه پایانی UpdateGradingPeriodSettings درخواست بدهد یا خیر.

پایتون 

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 انجام می شود، خواه دوره های درجه بندی فردی را اضافه کنید، دوره های درجه بندی موجود را تغییر دهید یا دوره درجه بندی را حذف کنید.

پایتون

در مثال زیر، منبع gradingPeriodSettings برای شامل دو دوره درجه بندی اصلاح شده است. بولی applyToExistingCoursework روی True تنظیم شده است که در هر دوره آموزشی موجود که بین تاریخ شروع و پایان یک دوره درجه بندی قرار می گیرد، gradingPeriodId تغییر می دهد. توجه داشته باشید که 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 خوانده می شود. هر کاربری، صرف نظر از مجوز، می تواند تنظیمات دوره های درجه بندی را در یک دوره بخواند.

پایتون 

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. دوره های درجه بندی با شناسه های جدید یا ناشناخته خطا محسوب می شوند.

پایتون

کد زیر بر اساس مثال موجود در این راهنما است. یک دوره درجه بندی جدید با عنوان "تابستان" ایجاد می شود. بولی applyToExistingCoursework در بدنه درخواست روی False تنظیم شده است.

برای انجام این کار، GradingPeriodSettings فعلی خوانده می‌شود، یک دوره نمره‌دهی جدید به لیست اضافه می‌شود، و بولی applyToExistingCoursework روی False تنظیم می‌شود. توجه داشته باشید که دوره‌های درجه‌بندی که قبلاً برای CourseWork موجود اعمال شده‌اند حذف نمی‌شوند. در مثال قبلی، دوره‌های درجه‌بندی «Semester 1» و «Semester 2» قبلاً برای CourseWork موجود اعمال شده‌اند و اگر applyToExistingCoursework در درخواست‌های بعدی روی False تنظیم شود، از CourseWork حذف نمی‌شوند. 

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 ادامه دارد ، به این معنی که اگر بولی در یک فراخوانی API قبلی روی True تنظیم شده باشد و تغییر نکرده باشد، به‌روزرسانی‌های بعدی دوره‌های درجه‌بندی در CourseWork موجود اعمال خواهد شد.

توجه داشته باشید که اگر در درخواستی به UpdateGradingPeriodSettings این مقدار بولی را از True به False تغییر دهید، فقط تغییرات جدیدی که در GradingPeriodSettings ایجاد می‌کنید در CourseWork موجود اعمال نمی‌شود. هر گونه اطلاعات دوره درجه‌بندی که در تماس‌های API قبلی، زمانی که بولی روی True تنظیم شده بود، در CourseWork اعمال شود، حذف نمی‌شود. یک راه مفید برای فکر کردن در مورد این تنظیم بولی این است که از مرتبط کردن CourseWork موجود با دوره های درجه بندی پیکربندی شده شما پشتیبانی می کند، اما از حذف ارتباط های موجود بین CourseWork و دوره های درجه بندی پیکربندی شده پشتیبانی نمی کند.

اگر عنوان یک دوره نمره‌دهی را حذف یا تغییر دهید، این تغییرات در تمام CourseWork موجود منتشر می‌شود، بدون توجه به تنظیم بولی applyToExistingCoursework .

یک دوره درجه بندی فردی را در لیست به روز کنید

برای اصلاح برخی از داده‌های مرتبط با دوره رتبه‌بندی موجود، شناسه دوره رتبه‌بندی موجود را در فهرست با داده‌های اصلاح‌شده قرار دهید.

پایتون

در این مثال، تاریخ پایان دوره درجه‌بندی «تابستان» اصلاح می‌شود. فیلد applyToExistingCoursework روی True تنظیم می شود. توجه داشته باشید که تنظیم این بولی روی True ، تمام دوره‌های درجه‌بندی پیکربندی‌شده را در CourseWork موجود اعمال می‌کند. در درخواست قبلی API، Boolean روی False تنظیم شده بود تا دوره درجه بندی "Summer" برای 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 حذف خواهد شد.

پایتون

برای ادامه مثال در این راهنما، دوره درجه بندی، "تابستان" را حذف کنید تا آن را حذف کنید. 

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 بر اساس فیلد scheduledTime ، gradingPeriodId را تعیین می کند. اگر هیچ یک از فیلدها مشخص نشده باشد، یا اگر محدوده تاریخ دوره رتبه بندی مطابقت نداشته باشد، هیچ gradingPeriodId در CourseWork تنظیم نخواهد شد.

2. دوره درجه بندی مرتبط سفارشی

اگر می‌خواهید CourseWork را با دوره درجه‌بندی متفاوتی نسبت به دوره‌ای که با dueDate یا scheduledTime هماهنگ است مرتبط کنید، می‌توانید هنگام ایجاد یا به‌روزرسانی CourseWork، فیلد gradingPeriodId را به‌صورت دستی تنظیم کنید. اگر به‌صورت دستی gradingPeriodId را تنظیم کنید، Classroom ارتباط خودکار دوره رتبه‌بندی مبتنی بر تاریخ را انجام نمی‌دهد.

3. عدم ارتباط دوره درجه بندی

اگر اصلاً نمی‌خواهید CourseWork با هیچ دوره درجه‌بندی مرتبط باشد، فیلد gradingPeriodId در درخواست CourseWork را روی یک رشته خالی تنظیم کنید ( gradingPeriodId : "" ).

اگر تاریخ سررسید به روز شود، برای شناسه دوره رتبه بندی چه اتفاقی می افتد؟

اگر فیلد CourseWork dueDate را به‌روزرسانی می‌کنید و می‌خواهید یک دوره درجه‌بندی سفارشی یا بدون ارتباط را حفظ کنید، باید dueDate و gradingPeriodId در updateMask و بدنه درخواست اضافه کنید. این به Classroom می‌گوید که gradingPeriodId با دوره درجه‌بندی که با dueDate جدید مطابقت دارد لغو نکند.

پایتون

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()
قبلی
تنظیم و به روز رسانی نمرات، تنظیم و به روز رسانی نمرات
بعدی
محدودیت ها