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

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

סקירה כללית

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

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

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

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

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

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

• המשתמש ששולח את הבקשה צריך להיות מורה בקורס או אדמין.
• למשתמש ששולח את הבקשה הוקצה רישיון ל-Google Workspace for Education Plus.
• לבעלי הקורס יש רישיון ל-Google Workspace for Education Plus.

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

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

אזהרה: נקודת הקצה userProfiles.checkUserCapability בודקת רק אם משתמש עומד בדרישות לשימוש ביכולת מסוימת, כמו שינוי תקופות מתן הציונים. אין בו מידע על התפקיד בקורס. לדוגמה, גם אם למשתמש יש את היכולת UPDATE_GRADING_PERIOD_SETTINGS, אם הוא תלמיד בקורס, בקשה לנקודת הקצה 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. תקופות למתן ציונים עם מזהים חדשים או לא מוכרים נחשבות שגיאות.

חשוב: הקפידו לכלול בבקשת UpdateGradingPeriodSettings את המזהים של כל תקופות מתן הציונים שאתם לא רוצים למחוק.

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.

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

חשוב: אם משתמשים בשפת התכנות Go, צריך לכלול את השדה ForceSendFields בגוף הבקשה כדי שספריית הלקוח תוכל לשלוח ערכי ברירת מחדל.

מה קורה למזהה התקופה למתן הציונים אם מעדכנים את תאריך היעד?

אם אתם מעדכנים את השדה 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()

חשוב: כשמעדכנים את השדה dueDate של CourseWork, צריך לכלול את השדה gradingPeriodId ב-updateMask ובגוף הבקשה כדי לשמור על שיוך מותאם אישית או על אי-שיוך. כך מוודאים ש-Classroom לא יחליף את השדה gradingPeriodId בשדה שתואם ל-dueDate החדש.