ניהול תקופות למתן ציונים באמצעות Classroom API

במדריך הזה מוסבר איך להשתמש בנקודות הקצה (endpoints) של תקופות מתן הציונים ב-Google Classroom API.

סקירה כללית

תקופות למתן ציונים נוצרות כדי לארגן את שיעורי הבית, המבחנים והפרויקטים בטווח תאריכים ספציפי. ‫Classroom API מאפשר למפתחים ליצור, לשנות ולקרוא תקופות למתן ציונים ב-Classroom בשם אדמינים ומורים. אפשר גם להשתמש ב-Classroom API כדי להגדיר תקופות למתן ציונים בכלי המשימות.

ב-Classroom API יש שתי נקודות קצה לקריאה ולכתיבה של מידע על תקופות למתן ציונים בקורס:

  • GetGradingPeriodSettings: מאפשר לקרוא את ההגדרות של תקופות למתן ציונים בקורס.
  • UpdateGradingPeriodSettings: מאפשרת לכם לנהל את ההגדרות של תקופות למתן ציונים בקורס על ידי הוספה, שינוי ומחיקה של תקופות למתן ציונים, והחלת התקופות למתן ציונים שהוגדרו על כל מטלות הלימוד הקיימות.

דרישות רישוי ודרישות סף

שינוי ההגדרות של תקופות למתן ציונים בקורס

כדי ליצור, לשנות או למחוק תקופות מתן ציונים בקורס באמצעות נקודת הקצה UpdateGradingPeriodSettings, צריך לעמוד בתנאים הבאים:

קריאת ההגדרות של תקופות למתן ציונים בקורס

אדמינים של הדומיין ומורים בקורס יכולים לקרוא את ההגדרות של תקופת מתן הציונים, בלי קשר לסוג הרישיון שהוקצה להם. כלומר, בקשות לנקודת הקצה GetGradingPeriodSettings מותרות בשם כל אדמין או מורה בדומיין.

הגדרת מזהה של תקופה למתן ציונים בעבודה

מורים בקורס יכולים לכלול את gradingPeriodId כשהם יוצרים או מעדכנים את כלי המטלות באמצעות ה-API, בלי קשר לרישיון שהוקצה להם.

בדיקת הזכאות של משתמש להגדרת תקופות למתן ציונים

מותר לשלוח בקשות לנקודת הקצה 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 הוא הגדרה קבועה שמאפשרת לארגן עבודות קודמות לתקופות מתן ציונים בלי לבצע קריאה נפרדת ל-API כדי לשנות את הערך gradingPeriodId לכל עבודה. אם המדיניות מוגדרת לערך 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 ישתנה בכל מטלת לימודים קיימת שחלה בין תאריך ההתחלה לתאריך הסיום של תקופה למתן ציונים. שימו לב שהשדה 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. שימו לב: תקופות למתן ציונים שכבר הוחלו על כלי המשימות הקיימות לא יוסרו. בדוגמה הקודמת, תקופות מתן הציונים 'סמסטר 1' ו'סמסטר 2' כבר הוחלו על מטלות קיימות, והן לא יוסרו מהמטלות אם הערך של applyToExistingCoursework מוגדר כ-False בבקשות הבאות.

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 נשמר, כלומר אם הערך הבוליאני הוגדר כ-True בקריאת API קודמת ולא שונה, עדכונים עתידיים לתקופות מתן הציונים יחולו על עבודות קיימות.

שימו לב שאם תשנו את הערך הבוליאני הזה מ-True ל-False בבקשה ל-UpdateGradingPeriodSettings, רק השינויים החדשים שתבצעו ב-GradingPeriodSettings לא יחולו על מטלות קיימות. כל מידע על תקופת מתן הציונים שחלים על כלי המשימות בקריאות קודמות ל-API, כשהערך הבוליאני הוגדר כ-True, לא יוסר. דרך טובה להבין את הגדרת הבוליאן הזו היא שהיא תומכת בשיוך של מטלות קיימות לתקופות מתן הציונים שהגדרתם, אבל היא לא תומכת בהסרת שיוכים קיימים בין מטלות לתקופות מתן ציונים שהגדרתם.

אם מוחקים או משנים את השם של תקופת מתן הציונים, השינויים האלה יועברו לכל מטלות הלימוד הקיימות, ללא קשר להגדרה של הערך הבוליאני applyToExistingCoursework.

עדכון של תקופה ספציפית למתן ציונים ברשימה

כדי לשנות נתונים מסוימים שמשויכים לתקופת מתן ציונים קיימת, צריך לכלול ברשימה את המזהה של תקופת מתן הציונים הקיימת עם הנתונים שרוצים לשנות.

Python

בדוגמה הזו, תאריך הסיום של תקופת מתן הציונים 'קיץ' ישתנה. השדה applyToExistingCoursework יוגדר ל-True. הערה: אם מגדירים את הערך הבוליאני הזה ל-True, כל תקופות הדיווח שהוגדרו יחולו על מטלות קיימות. בבקשת ה-API הקודמת, הערך הבוליאני הוגדר כ-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

מחיקת תקופה למתן ציונים

כדי למחוק תקופה למתן ציונים, משמיטים אותה מהרשימה. שימו לב: אם תקופה למתן ציונים נמחקת, כל הפניה לתקופה למתן ציונים בכלי המשימות והמטלות תמחק גם היא, בלי קשר להגדרה של applyToExistingCoursework.

Python

כדי להמשיך את הדוגמה במדריך הזה, משמיטים את תקופת מתן הציונים, Summer (קיץ), כדי למחוק אותה.

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 כולל את השדה 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. אין שיוך לתקופה למתן ציונים

אם לא רוצים לשייך את כלי המשימות לתקופת דיווח על ציונים, צריך להגדיר את השדה gradingPeriodId בבקשה של כלי המשימות למחרוזת ריקה (gradingPeriodId: "").

אם אתם משתמשים בשפת התכנות Go ולא רוצים להגדיר תקופת מתן ציונים, אתם צריכים לכלול את השדה ForceSendFields בגוף הבקשה. בספריית הלקוח של Go, ערכי ברירת מחדל מושמטים מבקשות API בגלל נוכחות של תג השדה omitempty בכל השדות. השדה ForceSendFields עוקף את זה ושולח את המחרוזת הריקה כדי לציין שלא רוצים להגדיר תקופת מתן ציונים לעבודה הזו. מידע נוסף זמין במאמרי העזרה של ספריית הלקוח של Google APIs Go.

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