תצוגה מקדימה למפתחים: זמינה כחלק מתוכנית התצוגה המקדימה למפתחים של Google Workspace, שמעניקה גישה מוקדמת לתכונות מסוימות. התכונה הזו זמינה בגרסה V1_20240401_PREVIEW ואילך. למידע נוסף, ראו גישה לממשקי ה-API של התצוגה המקדימה.

דף זה תורגם על ידי Cloud Translation API.

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

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

סקירה

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

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

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

דרישות רישוי

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

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

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

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

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

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

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

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

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

דרישות מוקדמות

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

ניהול המשאב `GradingPeriodSettings`

המשאב GradingPeriodSettings כולל רשימה של GradingPeriods בודדים ושדה בוליאני בשם applyToExistingCoursework.

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

הערך הבוליאני applyToExistingCoursework הוא הגדרה קבועה שמאפשרת לארגן את CourseWork שיצרתם בעבר בתקופות למתן ציונים, בלי שתצטרכו לבצע קריאה נפרדת ל-API כדי לשנות את gradingPeriodId בכל CourseWork. אם המדיניות מוגדרת לערך True, מערכת Classroom תגדיר באופן אוטומטי את הערך gradingPeriodId בכל הקורס הקיים של CourseWork, אם הערך של courseWork.dueDate נמצא בטווח של תאריכי ההתחלה והסיום הקיימים. אם לא הוגדר תאריך הגשה ב-CourseWork, מערכת Classroom תשתמש ברכיב courseWork.scheduledTime. אם אף אחד מהשדות לא קיים או שאין התאמה בין תאריכי ההתחלה והסיום של התקופה למתן ציונים, העבודה של הקורס לא תשויך לאף תקופה למתן ציונים.

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

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

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

עכשיו, כשאתם בטוחים שלמשתמש יש את הרישיון הנדרש לשינוי ההגדרות של התקופה למתן ציונים בקורס, תוכלו להתחיל לשלוח בקשות לנקודת הקצה (endpoint) UpdateGradingPeriodSettings. שינויים במשאב GradingPeriodSettings מתבצעים באמצעות נקודת הקצה UpdateGradingPeriodSettings, גם אם אתם מוסיפים תקופות נפרדות למתן ציונים, משנים את התקופות הקיימות למתן ציונים או מוחקים תקופה למתן ציונים.

Python

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

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

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

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

קוראים את הרשימה של התקופות למתן ציונים במשאב GradingPeriodSettings באמצעות נקודת הקצה GetGradingPeriodSettings.
מבצעים את השינויים הרצויים ברשימת התקופות למתן ציונים.
שולחים את הרשימה החדשה של התקופות למתן ציונים בבקשה אל UpdateGradingPeriodSettings.

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

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

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

Python

הקוד הבא יתבסס על הדוגמה במדריך הזה. נוצרת תקופה חדשה למתן ציונים בשם Summer. הערך הבוליאני applyToExistingCoursework מוגדר ל-False בגוף הבקשה.

כדי לעשות זאת, המערכת תקרא את הערך בשדה GradingPeriodSettings הנוכחי, יתווספו לרשימה תקופה חדשה למתן ציונים והערך הבוליאני applyToExistingCoursework יוגדר ל-False. חשוב לזכור שתקופות למתן ציונים שכבר הוחלו על CourseWork לא יוסרו. בדוגמה הקודמת, התקופות למתן ציונים 'סמסטר 1' ו'סמסטר 2' כבר הוחלו על CourseWork קיימים, והן לא יוסרו מ-CourseWork אם הערך applyToExistingCoursework יוגדר כ-False בבקשות הבאות.

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

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

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

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

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

Python

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

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

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

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

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

אם אתם מעדכנים את השדה dueDate של CourseWork ואתם רוצים לשמור על שיוך מותאם אישית של תקופה למתן ציונים או ללא שיוך של תקופה למתן ציונים, עליכם לכלול את dueDate ואת gradingPeriodId בגוף העדכון (במסכה ובגוף הבקשה). כך מערכת 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()

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

סקירה

דרישות רישוי

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

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

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

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

דרישות מוקדמות

ניהול המשאב GradingPeriodSettings

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

Python

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

Python

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

Python

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

Python

טיפים מועילים לגבי השדה הבוליאני applyToExistingCoursework

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

Python

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

Python

ניהול השדה gradingPeriodId ב-CourseWork

‫1. שיוך של תקופה למתן ציונים לפי תאריך

‫2. תקופה משויכת למתן ציונים בהתאמה אישית

3. אין שיוך לתקופה למתן ציונים

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

Python

ניהול המשאב `GradingPeriodSettings`

טיפים מועילים לגבי השדה הבוליאני `applyToExistingCoursework`

ניהול השדה `gradingPeriodId` ב-CourseWork