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