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

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

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

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

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

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

המדריך הזה כולל דוגמאות קוד ב-Python, ומבוסס על ההנחות הבאות:

פרויקט ב-Google Cloud. אפשר להגדיר אחד לפי ההוראות במאמר Python quickstart.
הוספתם את היקפי ההרשאות הבאים למסך ההסכמה של 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 מוגדר כ-True, מערכת Classroom תגדיר את הערך gradingPeriodId באופן אוטומטי לכל המטלות הקיימות ב-Coursework אם courseWork.dueDate נמצא בטווח התאריכים של תקופת הערכה קיימת. אם לא הוגדר תאריך הגשה למטלה, מערכת 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

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

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

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

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

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

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

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

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

Python

בדוגמה הזו, תאריך הסיום של תקופת המטלות 'קיץ' ישתנה. השדה applyToExistingCoursework יוגדר לערך True. הערה: הגדרת הערך הלוגי הזה ל-True תחול על כל תקופות המטלות שהוגדרו ב-CourseWork קיים. בבקשת ה-API הקודמת, הערך הבוליאני הוגדר כ-False כדי שתקופת הבדיקות 'קיץ' לא תחול על עבודות קיימות. עכשיו, אחרי שהשדה הבוליאני הזה מוגדר כ-True, תקופת המטלות 'קיץ' תחול על כל עבודות הקורס הקיימות שתואמות.

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

כדי להמשיך בדוגמה שבמדריך הזה, משמיטים את תקופת המטלות 'קיץ' כדי למחוק אותה.

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. שיוך של תקופות למתן ציונים על סמך תאריך

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

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

אם רוצים לשייך את CourseWork לתקופת הערכה שונה מזו שתואמת ל-dueDate או ל-scheduledTime, אפשר להגדיר את השדה gradingPeriodId באופן ידני כשיוצרים או מעדכנים את CourseWork. אם תגדירו את gradingPeriodId באופן ידני, מערכת Classroom לא תבצע את השיוך האוטומטי של תקופות הציונים לפי תאריך.

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

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