使用 Classroom API 管理評分週期

本指南說明如何在 Google Classroom API 中使用評分期間端點。

總覽

建立評分期間，可將家庭作業、測驗和專案整理至特定日期範圍內。Classroom API 可讓開發人員代表管理員和老師，在 Classroom 中建立、修改及查看評分期間。您也可以使用 Classroom API 在 CourseWork 中設定評分期間。

Classroom API 提供兩個端點，可讓您在課程中讀取及寫入評分週期資訊：

  • GetGradingPeriodSettings：可讓您查看課程中的評分期間設定。
  • UpdateGradingPeriodSettings：可新增、修改及刪除評分期間，以及將設定的評分期間套用至所有現有的 CourseWork，藉此管理課程的評分週期設定。

授權規定

修改課程的評分期間設定

如要使用 UpdateGradingPeriodSettings 端點建立、修改或刪除課程的評分期間，必須符合下列條件：

查看課程中的評分週期設定

無論指派的授權為何，課程的網域管理員和老師都可以讀取評分期間的設定。這表示任何網域管理員或老師都允許向 GetGradingPeriodSettings 端點發出的要求。

在 CourseWork 中設定評分期間 ID

無論指派的授權為何，課程的老師使用 API 建立或更新 CourseWork 時，都可以加入 gradingPeriodId。

檢查使用者的資格，並設定評分週期

任何管理員或老師都允許向 checkGradingPeriodsSetupEligibility 端點發出的要求。您可以使用這個選項判斷使用者能否修改課程的評分期間。

先備知識

本指南提供 Python 的程式碼範例，並假設您已：

  • Google Cloud 專案。您可以按照 Python 快速入門導覽課程中的操作說明進行設定。
  • 已將下列範圍新增至專案的 OAuth 同意畫面：
    • https://www.googleapis.com/auth/classroom.courses
    • https://www.googleapis.com/auth/classroom.coursework.students
  • 應修改評分期間的課程 ID。課程擁有者必須具備 Google Workspace for Education Plus 授權。
  • 透過 Google Workspace for Education Plus 授權存取老師或管理員的憑證。您需要老師的憑證才能建立或修改 CourseWork。如果管理員不是課程的老師，則無法建立或修改 CourseWork。

管理 GradingPeriodSettings 資源

GradingPeriodSettings 資源包含個別 GradingPeriods 清單，以及名為 applyToExistingCoursework 的布林值欄位。

GradingPeriods 清單代表課程中所有個別評分期間。您必須為清單中各個評分週期指定標題、開始日期和結束日期。課程中的每個評分期間都必須有不重複的標題，且不同評分期間的開始與結束日期不可重疊。每個評分週期都有專屬的 Classroom API 指派 ID。

applyToExistingCoursework 布林值是持續性的設定，可讓您管理先前建立的 CourseWork，無需另外發出 API 呼叫來修改每個 CourseWork 的 gradingPeriodId。如果設為 True，且 courseWork.dueDate 落在現有評分週期的開始與結束日期範圍內，Classroom 就會自動在所有現有 CourseWork 中設定 gradingPeriodId。如未在 CourseWork 中設定截止日期，Classroom 會使用 courseWork.scheduledTime。如果現有評分期間的開始與結束日期皆無任何欄位，或是現有評分期間的開始與結束日期內皆不相符，CourseWork 就不會與任何評分週期建立關聯。

決定使用者能否修改課程的評分期間設定

由於只有具備特定授權的使用者才能在 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，這會針對任何介於一個評分週期開始與結束日期之間的現有 CourseWork 修改 gradingPeriodId。請注意，updateMask 包含這兩個欄位。在回應中傳回個別評分期間的 ID 後，請儲存這些評分期間的 ID。您需要使用這些 ID 更新評分期間 (如有需要)。

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

查看評分週期設定

系統會使用 GetGradingPeriodSettings 端點讀取 GradingPeriodSettings。任何使用者 (無論是否具備授權) 都可以查看課程的評分期間設定。

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

在清單中加入個別評分週期

如要更新個別評分期間，必須按照「讀取 - 修改 - 寫入」模式完成更新。這代表您應該：

  1. 使用 GetGradingPeriodSettings 端點查看 GradingPeriodSettings 資源中的評分期間清單。
  2. 依據評分週期清單做出所選修改。
  3. 請在要求中將新的評分期間清單傳送給 UpdateGradingPeriodSettings。

這個模式可協助您確保課程中每個評分期間的標題都不同，且評分期間的開始與結束日期不重疊。

關於更新評分週期清單，請留意下列規則：

  1. 新增至清單但沒有 ID 的評分期間會視為「新增」。
  2. 系統會將清單中「缺少」的評分期間視為「刪除」。
  3. 具有現有 ID 但修改後的資料會視為「編輯」。未修改的屬性會保持原樣。
  4. 具有新 ID 或不明 ID 的評分期間會視為「錯誤」。

Python

下列程式碼將以本指南中的範例為基礎。系統隨即會使用「夏季」這個標題建立新的評分期間。要求主體中的 applyToExistingCoursework 布林值設為 False。

為此，系統會讀取目前的 GradingPeriodSettings，並在清單中加入新的評分週期，而 applyToExistingCoursework 布林值會設為 False。請注意，已套用至現有 CourseWork 的評分期間不會移除。在先前的範例中，「Semester 1」和「Semester 2」評分期間已套用至現有的 CourseWork，而且若後續要求中的 applyToExistingCoursework 設為「False」，則不會從 CourseWork 中移除。

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 布林值會「保留」，也就是說，如果在先前的 API 呼叫中將布林值設為 True，且未變更，之後對評分期間的更新將套用至現有的 CourseWork。

請注意，如果您在對 UpdateGradingPeriodSettings 的要求中將此佈林值從 True 變更為 False，則只有您對 GradingPeriodSettings 的新變更不會套用至現有 CourseWork。布林值設為 True 時，在先前的 API 呼叫中套用至 CourseWork 的所有評分期間資訊都不會移除。如果您想瞭解這項布林設定，可以把現有 CourseWork 與所設評分週期建立關聯，但無法移除 CourseWork 與已設定評分週期之間的現有關聯。

如果您刪除或變更評分期間的標題，無論 applyToExistingCoursework 布林值的設定為何，這些變更都會傳播至所有現有的 CourseWork。

更新清單中的個別評分週期

如要修改部分與現有評分週期相關聯的資料，請在清單中加入現有評分週期的 ID，以及修改後的資料。

Python

在這個範例中，「夏季」評分期間的結束日期會修改。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

刪除個別評分週期

如要刪除評分期間，請在清單中省略評分週期。請注意，如果刪除評分期間，無論 applyToExistingCoursework 設定為何，系統都會刪除 CourseWork 中評分期間的任何參考資料。

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

管理 CourseWork 中的「gradingPeriodId」欄位

CourseWork 資源包含 gradingPeriodId 欄位。您可以使用 CourseWork 端點讀取及寫入與 CourseWork 相關聯的評分週期。管理這項關聯的方法有三種：

  • 自動以日期為依據的評分週期關聯
  • 自訂相關的評分週期
  • 沒有評分週期關聯

1. 以日期為依據的評分週期關聯

建立 CourseWork 時，您可以允許 Classroom 為您處理評分期關聯作業。如要這麼做，請在 CourseWork 要求中省略 gradingPeriodId 欄位。接著，請在 CourseWork 要求中指定 dueDate 或 scheduledTime 欄位。如果 dueDate 屬於現有的評分日期範圍，Classroom 會在 CourseWork 上設定該評分期間 ID。如未指定 dueDate 欄位，Classroom 會根據 scheduledTime 欄位決定 gradingPeriodId。如果未指定任何欄位，或是沒有相符的評分週期日期範圍，系統就不會在 CourseWork 中設定任何 gradingPeriodId。

2. 自訂相關聯的評分週期

如要將 CourseWork 連結至與 dueDate 或 scheduledTime 對應評分期間不同的評分週期，您可以在建立或更新 CourseWork 時手動設定 gradingPeriodId 欄位。如果您手動設定 gradingPeriodId，Classroom 將不會執行以日期為依據的評分週期關聯。

3. 沒有相關聯的評分週期

如果您完全不想將 CourseWork 與任何評分週期建立關聯，請將 CourseWork 要求中的 gradingPeriodId 欄位設為空白字串 (gradingPeriodId："")。

如果更新截止日，評分週期 ID 會受到什麼影響？

如要更新 CourseWork dueDate 欄位，並想保留自訂或不含評分期間的關聯，請在 updateMask 和要求主體中加入 dueDate 和 gradingPeriodId。這會指示 Classroom 不要使用與新 dueDate 相符的評分期間覆寫 gradingPeriodId。

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