使用 Classroom API 管理評分週期

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

總覽

評分週期可將作業、測驗和專案分門別類，歸入特定日期範圍。Classroom API 可讓開發人員代表管理員和老師，在 Classroom 中建立、修改及讀取評分期間。您也可以使用 Classroom API 在 CourseWork 中設定評分週期。

Classroom API 提供兩個端點，可讀取及寫入課程的評分期間資訊：

  • GetGradingPeriodSettings：可讓您讀取課程中的評分期間設定。
  • UpdateGradingPeriodSettings：讓您管理課程中的評分期間設定，方法是新增、修改和刪除評分期間，並將已設定的評分期間套用至所有現有的 CourseWork。

授權和資格規定

修改課程的評分週期設定

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

讀取課程中的評分週期設定

無論指派的授權為何，課程的網域管理員和老師都可以讀取評分期間設定。也就是說，系統會允許任何網域管理員或老師代表提出 GetGradingPeriodSettings 端點要求。

在 CourseWork 上設定評分週期 ID

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

檢查使用者是否符合設定評分期間的資格

系統會允許代表任何管理員或老師，向 userProfiles.checkUserCapability 端點提出要求。用於判斷使用者是否可以修改評分期間。

必要條件

本指南提供 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 就會自動為所有現有的課程作業設定 gradingPeriodId。如果未在 CourseWork 中設定截止日期，Classroom 會使用 courseWork.scheduledTime。如果兩個欄位都沒有值，或是在現有評分期間的開始和結束日期中沒有相符項目，CourseWork 就不會與任何評分期間建立關聯。

判斷使用者是否可修改課程的評分期間設定

Classroom API 提供 userProfiles.checkUserCapability 端點，可協助您主動判斷使用者是否能向 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 端點發出要求。無論是新增個別評分期間、修改現有評分期間，還是刪除評分期間，都必須使用 UpdateGradingPeriodSettings 端點執行 GradingPeriodSettings 資源的任何修改作業。

Python

在以下範例中，我們修改 gradingPeriodSettings 資源，加入兩個評分期間。applyToExistingCoursework 布林值設為 True 時，系統會修改評分期間開始和結束日期之間任何現有課程作業的 gradingPeriodId。請注意，updateMask 包含這兩個欄位。在回應中傳回個別評分期間的 ID 後，請儲存這些 ID。視需要使用這些 ID 更新評分週期。

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. 使用 GetGradingPeriodSettings 端點讀取 GradingPeriodSettings 資源中的評分期間清單。
  2. 在評分期間清單中進行所選修改。
  3. 在要求中傳送新的評分期間清單給 UpdateGradingPeriodSettings。

這個模式可確保課程中各個評分期間的名稱皆不重複，且評分期間的開始與結束日期不會重疊。

請注意更新評分期間清單的規則：

  1. 未附 ID 新增至清單的評分週期視為新增。
  2. 清單中缺少的評分期間會視為刪除。
  3. 評分期間具有現有 ID，但資料已經過修改，會被視為編輯。未修改的屬性則維持原樣。
  4. 含有新 ID 或不明 ID的評分期間會視為錯誤。

Python

以下程式碼會以本指南中的範例為基礎。系統會建立名為「Summer」的新評分期間。在要求主體中，applyToExistingCoursework 布林值設為 False。

做法是讀取目前的 GradingPeriodSettings，將新的評分期間新增至清單，並將 applyToExistingCoursework 布林值設為 False。請注意，已套用至現有課程作業的任何評分期間都不會遭到移除。在上述範例中，「Semester 1」和「Semester 2」評分期間已套用至現有的 CourseWork，如果在後續要求中將 applyToExistingCoursework 設為 False，就不會從 CourseWork 中移除。

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

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

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

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

如要修改與現有評分期間相關聯的部分資料，請在包含修改資料的清單中加入現有評分期間的 ID。

Python

在這個範例中，系統會修改「Summer」評分期間的結束日期。applyToExistingCoursework 欄位會設為 True。請注意，將這個布林值設為 True 後，系統會將所有已設定的評分期間套用至現有的 CourseWork。在先前的 API 要求中，布林值已設為 False，因此「Summer」評分期間不會套用至現有的 CourseWork。這個布林值欄位已設為 True，因此「Summer」評分期間會套用至所有相符的現有 CourseWork。

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 設定為何，如果刪除評分期間，CourseWork 中任何與評分期間相關的內容也會一併刪除。

Python

如要繼續本指南中的範例，請略過「夏季」評分期間，以便刪除該期間。

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

管理 CourseWork 上的 gradingPeriodId 欄位

CourseWork 資源包含 gradingPeriodId 欄位。您可以使用 CourseWork 端點來讀取及寫入與 CourseWork 相關聯的評分期間。您可以透過下列三種方式管理這項關聯：

  • 自動根據日期建立評分期間關聯
  • 自訂相關評分週期
  • 沒有評分週期關聯

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

建立課程作業時，您可以讓 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: "")。

如果您使用 Go 程式設計語言，且想要設定不評分期間，請在要求主體中加入 ForceSendFields 欄位。使用 Go 用戶端程式庫時，由於所有欄位都含有 omitempty 欄位標記，因此 API 要求會省略預設值。ForceSendFields 欄位會略過這項操作，並傳送空白字串，表示您不想為該 CourseWork 設定任何評分期間。詳情請參閱 Google APIs Go 用戶端程式庫說明文件。

Go

courseWork := &classroom.CourseWork{
  Title: "Homework questions",
  WorkType: "ASSIGNMENT",
  State: "DRAFT",
  // ...other CourseWork fields...
  GradingPeriodId: "",
  ForceSendFields: []string{"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_service.courses().courseWork().patch(
  courseId=course_id, id=coursework_id, body=body,
  updateMask='dueDate,dueTime,gradingPeriodId') # include the gradingPeriodId field in the updateMask
.execute()
上一頁
設定及更新成績
下一頁
限制