開始使用評分量表

老師為學生評分時，可以使用 rubric 範本 提交內容。Classroom API 可讓您代表 管理這些評分量表

圖 1. 查看 Classroom 作業的評分量表範例。

本指南說明 Rubrics API 的基本概念和功能。詳情請見 請參閱相關的說明中心文章，瞭解「一般 評分量表的架構與評分量表結構 評分作業。

必要條件

本指南假設您已具備下列項目：

• Python 3.8.6 以上版本
• pip 套件管理工具
• Google Cloud 專案。
• 擁有 Google Classroom 服務的 Google Workspace for Education 帳戶 啟用。
• 至少擁有一個測驗學生帳戶的測驗課程。如果您沒有 可以用於測試的 Classroom 課程 在使用者介面中建立 新增測試學生。

授權電腦版應用程式憑證

如要以使用者身分進行驗證，並存取應用程式中的使用者資料，您需要 建立一或多個 OAuth 2.0 用戶端 ID。用戶端 ID 可用來識別 單一應用程式傳送至 Google 的 OAuth 伺服器。如果您的應用程式在多個平台上運作 您都必須為每個平台分別建立用戶端 ID。

1. 前往 存取 Google Cloud 控制台
2. 按一下「建立憑證」>OAuth 用戶端 ID。
3. 按一下「應用程式類型」>電腦版應用程式。
4. 在「名稱」欄位中輸入憑證的名稱。這個名稱僅供 這項工具會顯示在 Google Cloud 控制台中例如「評分量表預覽用戶端」。
5. 按一下「建立」，畫面上會顯示 OAuth 用戶端建立的畫面，其中顯示新的 用戶端 ID 和用戶端密碼。
6. 依序點選「Download JSON」和「OK」。新建立的憑證 這組 ID 會顯示在 OAuth 2.0 用戶端 ID 之下。
7. 將下載的 JSON 檔案儲存為 credentials.json，然後移動檔案到 工作目錄
8. 按一下「建立憑證」>API 金鑰，並記下 API 金鑰。

詳情請參閱「建立存取認證」。

設定 OAuth 範圍

視專案現有的 OAuth 範圍而定，您可能需要 以及範圍

1. 前往「OAuth 同意畫面」。
2. 按一下「編輯應用程式」>儲存並繼續，返回「範圍」畫面。
3. 按一下「新增或移除範圍」。
4. 請新增下列範圍 (如果您尚未設定的話)：
   • https://www.googleapis.com/auth/classroom.coursework.students
   • https://www.googleapis.com/auth/classroom.courses
5. 然後按一下「更新」>儲存並繼續 >儲存並繼續 > 返回資訊主頁。

詳情請參閱「設定 OAuth 同意畫面」一文。 內容。

classroom.coursework.students 範圍允許讀取及寫入 評分量表 (以及 CourseWork 的存取權) 和 classroom.courses 範圍 提供讀取及寫課程的功能

參考文件列出了特定方法所需的範圍 。請參閱 courses.courseWork.rubrics.create 授權範圍 舉例來說您可以在 Google 的 OAuth 2.0 範圍中查看所有 Classroom 範圍 API由於 API 仍在預先發布版，因此這裡未提及評分量表。

設定範例

在工作目錄中，安裝 Python 適用的 Google 用戶端程式庫：

pip install --upgrade google-api-python-client google-auth-httplib2 google-auth-oauthlib

注意： 評分量表相關的欄位和方法不會在標準用戶端中公開 因為 Rubrics CRUD 目前在開發人員預覽版中以下範例 在程式庫產生期間指定 DEVELOPER_PREVIEW 標籤，以啟用 曝光請參閱「存取預覽 API」，進一步瞭解如何使用預先發布版 API 用戶端程式庫

建立名為 main.py 的檔案，以便建構用戶端程式庫並授權 使用 API 金鑰取代 YOUR_API_KEY：

import json
import os.path

from google.auth.transport.requests import Request
from google.oauth2.credentials import Credentials
from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError

# If modifying these scopes, delete the file token.json.
SCOPES = ['https://www.googleapis.com/auth/classroom.courses',
          'https://www.googleapis.com/auth/classroom.coursework.students']

def build_authenticated_service(api_key):
    """Builds the Classroom service."""
    creds = None
    # The file token.json stores the user's access and refresh tokens, and is
    # created automatically when the authorization flow completes for the first
    # time.
    if os.path.exists('token.json'):
        creds = Credentials.from_authorized_user_file('token.json', SCOPES)
    # If there are no (valid) credentials available, let the user log in.
    if not creds or not creds.valid:
        if creds and creds.expired and creds.refresh_token:
            creds.refresh(Request())
        else:
            flow = InstalledAppFlow.from_client_secrets_file(
                'credentials.json', SCOPES)
            creds = flow.run_local_server(port=0)
        # Save the credentials for the next run.
        with open('token.json', 'w') as token:
            token.write(creds.to_json())

    try:
        # Build the Classroom service.
        service = build(
            serviceName="classroom",
            version="v1",
            credentials=creds,
            discoveryServiceUrl=f"https://classroom.googleapis.com/$discovery/rest?labels=DEVELOPER_PREVIEW&key={api_key}")

        return service

    except HttpError as error:
        print('An error occurred: %s' % error)

if __name__ == '__main__':
    service = build_authenticated_service(YOUR_API_KEY)

使用 python main.py 執行指令碼。系統會提示您登入 同意授予 OAuth 範圍

建立作業

評分量表已與作業 (或「CourseWork」) 建立關聯， 在該 CourseWork 的情境下產生意義評分量表只會在 建立父項 CourseWork 項目的 Google Cloud 專案。目的 請使用指令碼建立新的 CourseWork 作業。

將下列指令新增至 main.py：

def get_latest_course(service):
    """Retrieves the last created course."""
    try:
        response = service.courses().list(pageSize=1).execute()
        courses = response.get("courses", [])
        if not courses:
            print("No courses found. Did you remember to create one in the UI?")
            return
        course = courses[0]
        return course

    except HttpError as error:
        print(f"An error occurred: {error}")
        return error

def create_coursework(service, course_id):
    """Creates and returns a sample coursework."""
    try:
        coursework = {
            "title": "Romeo and Juliet analysis.",
            "description": """Write a paper arguing that Romeo and Juliet were
                                time travelers from the future.""",
            "workType": "ASSIGNMENT",
            "state": "PUBLISHED",
        }
        coursework = service.courses().courseWork().create(
            courseId=course_id, body=coursework).execute()
        return coursework

    except HttpError as error:
        print(f"An error occurred: {error}")
        return error

現在更新 main.py，擷取剛才所測試測試類別的 course_id 已建立新的作業範例，然後擷取作業的 coursework_id:

if __name__ == '__main__':
    service = build_authenticated_service(YOUR_API_KEY)

    course = get_latest_course(service)
    course_id = course.get("id")
    course_name = course.get("name")
    print(f"'{course_name}' course ID: {course_id}")

    coursework = create_coursework(service, course_id)
    coursework_id = coursework.get("id")
    print(f"Assignment created with ID {coursework_id}")

    #TODO(developer): Save the printed course and coursework IDs.

儲存 course_id 和 coursework_id。所有評分量表都必須使用這些評分量表 作業。

您現在可以在 Classroom 取得「CourseWork」範例。

圖 2. 查看 Classroom 中的作業範例。

建立評分量表

現在可以開始管理評分量表。

您可以在 CourseWork 上建立評分量表，並在其中加入含有以下內容的 Create 呼叫 完整評分量表物件，其中省略條件與等級的 ID 屬性 (這些是在建立時產生的)。

注意： 由於評分量表 CRUD 處於開發人員預覽模式，因此系統會呼叫評分量表服務 如未指定適當的 previewVersion，則會傳回錯誤。 和所有與評分量表相關的後續呼叫，請將 previewVersion 欄位改為 V1_20231110_PREVIEW。請參閱存取預覽 API，瞭解如何執行以下操作： 進一步瞭解如何指定版本，並透過藍圖瞭解哪個版本 支援。

在 main.py 中新增下列函式：

def create_rubric(service, course_id, coursework_id):
    """Creates an example rubric on a coursework."""
    try:
        body = {
            "criteria": [
                {
                    "title": "Argument",
                    "description": "How well structured your argument is.",
                    "levels": [
                        {"title": "Convincing",
                         "description": "A compelling case is made.", "points": 30},
                        {"title": "Passable",
                         "description": "Missing some evidence.", "points": 20},
                        {"title": "Needs Work",
                         "description": "Not enough strong evidence..", "points": 0},
                    ]
                },
                {
                    "title": "Spelling",
                    "description": "How well you spelled all the words.",
                    "levels": [
                        {"title": "Perfect",
                         "description": "No mistakes.", "points": 20},
                        {"title": "Great",
                         "description": "A mistake or two.", "points": 15},
                        {"title": "Needs Work",
                         "description": "Many mistakes.", "points": 5},
                    ]
                },
                {
                    "title": "Grammar",
                    "description": "How grammatically correct your sentences are.",
                    "levels": [
                        {"title": "Perfect",
                         "description": "No mistakes.", "points": 20},
                        {"title": "Great",
                         "description": "A mistake or two.", "points": 15},
                        {"title": "Needs Work",
                         "description": "Many mistakes.", "points": 5},
                    ]
                },
            ]
        }

        rubric = service.courses().courseWork().rubrics().create(
            courseId=course_id, courseWorkId=coursework_id, body=body,
            # Specify the preview version. Rubrics CRUD capabilities are
            # supported in V1_20231110_PREVIEW and later.
            previewVersion="V1_20231110_PREVIEW"
            ).execute()
        print(f"Rubric created with ID {rubric.get('id')}")
        return rubric

    except HttpError as error:
        print(f"An error occurred: {error}")
        return error

接著更新並執行 main.py，即可使用 Course 建立評分量表範例 和前 CourseWork 個 ID：

if __name__ == '__main__':
    service = build_authenticated_service(YOUR_API_KEY)

    rubric = create_rubric(service, YOUR_COURSE_ID, YOUR_COURSEWORK_ID)
    print(json.dumps(rubric, indent=4))

注意： 請注意，傳回的評分量表含有 previewVersion 建立通話。與預覽方法呼叫相關聯的資源也包含 用於通話的 previewVersion 做為唯讀欄位，方便您瞭解 目前使用的版本。

使用評分量表的注意事項：

• Classroom 使用者介面會反映相關標準和等級順序。
• 得分等級 (含有 points 屬性的項目) 必須依點排序 按遞增或遞減順序排列 (無法隨機排序)。
• 老師可以重新排列標準和評分等級 (但無法重新評分) 並變更資料在資料中的順序。

請參閱限制，進一步瞭解評分量表結構的注意事項。

返回使用者介面，您應該會看到作業的評分量表。

圖 3. 查看 Classroom 作業的評分量表範例。

閱讀評分量表

您可以利用標準 List 和 Get 方法讀取評分量表。

一份作業最多只能有一個評分量表，因此 List 看起來可能會像這樣 可能不符合直覺，不過如果您尚未取得評分量表 ID 也很有幫助。如果有 沒有與 CourseWork 相關聯的評分量表，List 回應空白。

在 main.py 中新增下列函式：

def get_rubric(service, course_id, coursework_id):
    """
    Get the rubric on a coursework. There can only be at most one.
    Returns null if there is no rubric.
    """
    try:
        response = service.courses().courseWork().rubrics().list(
            courseId=course_id, courseWorkId=coursework_id,
            # Specify the preview version. Rubrics CRUD capabilities are
            # supported in V1_20231110_PREVIEW and later.
            previewVersion="V1_20231110_PREVIEW"
            ).execute()

        rubrics = response.get("rubrics", [])
        if not rubrics:
            print("No rubric found for this assignment.")
            return
        rubric = rubrics[0]
        return rubric

    except HttpError as error:
        print(f"An error occurred: {error}")
        return error

更新並執行 main.py，擷取您新增的評分量表：

if __name__ == '__main__':
    service = build_authenticated_service(YOUR_API_KEY)

    rubric = get_rubric(service, YOUR_COURSE_ID, YOUR_COURSEWORK_ID)
    print(json.dumps(rubric, indent=4))

    #TODO(developer): Save the printed rubric ID.

請記下評分量表中的 id 屬性，以供後續步驟使用。

您必須有評分量表 ID，Get 才能正常運作。在函式中使用 Get 可能看起來像這樣：

def get_rubric(service, course_id, coursework_id, rubric_id):
    """
    Get the rubric on a coursework. There can only be at most one.
    Returns a 404 if there is no rubric.
    """
    try:
        rubric = service.courses().courseWork().rubrics().get(
            courseId=course_id,
            courseWorkId=coursework_id,
            id=rubric_id,
            # Specify the preview version. Rubrics CRUD capabilities are
            # supported in V1_20231110_PREVIEW and later.
            previewVersion="V1_20231110_PREVIEW"
        ).execute()

        return rubric

    except HttpError as error:
        print(f"An error occurred: {error}")
        return error

如果沒有評分量表，此實作會傳回 404。

更新評分量表

評分量表的更新是透過 Patch 呼叫完成。由於結構複雜 更新必須使用「讀取 - 修改 - 寫入」模式， 整個 criteria 屬性都會被取代。

更新規則如下：

1. 系統會考慮沒有 ID 新增的條件或等級 新增。
2. 系統會考慮之前「缺少」的條件或等級 刪除。
3. 系統會考慮已有 ID 但經過修改的資料的條件或層級 編輯。未修改的屬性會保持原樣。
4. 透過新的或不明 ID 提供的條件或層級時，則視為適用 錯誤。
5. 系統會將新條件和等級的順序視為新的 UI 順序 (同時遵循上述限制)。

新增用於更新評分量表的函式：

def update_rubric(service, course_id, coursework_id, rubric_id, body):
    """
    Updates the rubric on a coursework.
    """
    try:
        rubric = service.courses().courseWork().rubrics().patch(
            courseId=course_id,
            courseWorkId=coursework_id,
            id=rubric_id,
            body=body,
            updateMask='criteria',
            # Specify the preview version. Rubrics CRUD capabilities are
            # supported in V1_20231110_PREVIEW and later.
            previewVersion="V1_20231110_PREVIEW"
        ).execute()

        return rubric

    except HttpError as error:
        print(f"An error occurred: {error}")
        return error

在這個範例中，criteria 欄位指定的修改方式為 updateMask。

接著修改 main.py，為上述的每次更新進行變更 規則：

if __name__ == '__main__':
    service = build_authenticated_service(YOUR_API_KEY)

    # Get the latest rubric.
    rubric = get_rubric(service, YOUR_COURSE_ID, YOUR_COURSEWORK_ID)
    criteria = rubric.get("criteria")
    """
    The "criteria" property should look like this:
    [
        {
            "id": "NkEyMdMyMzM2Nxkw",
            "title": "Argument",
            "description": "How well structured your argument is.",
            "levels": [
                {
                    "id": "NkEyMdMyMzM2Nxkx",
                    "title": "Convincing",
                    "description": "A compelling case is made.",
                    "points": 30
                },
                {
                    "id": "NkEyMdMyMzM2Nxky",
                    "title": "Passable",
                    "description": "Missing some evidence.",
                    "points": 20
                },
                {
                    "id": "NkEyMdMyMzM2Nxkz",
                    "title": "Needs Work",
                    "description": "Not enough strong evidence..",
                    "points": 0
                }
            ]
        },
        {
            "id": "NkEyMdMyMzM2Nxk0",
            "title": "Spelling",
            "description": "How well you spelled all the words.",
            "levels": [...]
        },
        {
            "id": "NkEyMdMyMzM2Nxk4",
            "title": "Grammar",
            "description": "How grammatically correct your sentences are.",
            "levels": [...]
        }
    ]
    """

    # Make edits. This example will make one of each type of change.

    # Add a new level to the first criteria. Levels must remain sorted by
    # points.
    new_level = {
        "title": "Profound",
        "description": "Truly unique insight.",
        "points": 50
    }
    criteria[0]["levels"].insert(0, new_level)

    # Remove the last criteria.
    del criteria[-1]

    # Update the criteria titles with numeric prefixes.
    for index, criterion in enumerate(criteria):
        criterion["title"] = f"{index}: {criterion['title']}"

    # Resort the levels from descending to ascending points.
    for criterion in criteria:
        criterion["levels"].sort(key=lambda level: level["points"])

    # Update the rubric with a patch call.
    new_rubric = update_rubric(
        service, YOUR_COURSE_ID, YOUR_COURSEWORK_ID, YOUR_RUBRIC_ID, rubric)

    print(json.dumps(new_rubric, indent=4))

現在老師就能在 Classroom 中反映這些變更。

圖 4. 查看已更新的評分量表。

注意： 開始評分後，這些編輯規則就會受到限制。

查看經評分量表評分的作業

目前無法使用 API 的評分量表批改學生繳交的作業，但 使用評分量表完成評分後，您就能查看評分量表成績 也別忘了善加利用 Classroom UI

以學生身分在 Classroom UI 中完成並繳交作業範例。 然後以老師身分手動使用評分量表批改作業。

圖 5.老師在評分期間查看評分量表。

提示： 把握這個絕佳機會，熟悉 老師在使用評分量表時可能遇到的情況比方說，請觀察老師 會覆寫所選等級的條件分數，以及作業的總分 然後完全略過選擇層級的步驟詳情請見 限制。

使用評分量表進行評分的學生繳交作業有兩項 屬性：draftRubricGrades 和 assignedRubricGrades，代表 老師在草稿和指派評分期間選擇的分數和等級 狀態。

此外，相關評分量表的學生繳交作業中會含有rubricId ] 欄位。這代表了與下列項目相關的最新評分量表 如果老師刪除並重新建立 CourseWork 資源，這個值可能會有所變更 。

您可以使用現有的 studentSubmissions.Get 和 studentSubmissions.List 方法，以便查看已評分的作業。

警告： rubricId、draftRubricGrades 和 assignedRubricGrades 欄位 根據預設，Classroom API 中不會顯示任何項目，因此只有使用者能存取 。也就是說，你必須設定適當的 previewVersion 即可擷取這些項目。有別於評分量表服務，系統會在 省略版本時，提交服務不會傳回錯誤。這些欄位 都已在參考說明文件中加註。

將下列函式加入 main.py 以列出學生繳交的內容：

def get_latest_submission(service, course_id, coursework_id):
    """Retrieves the last submission for an assignment."""
    try:
        response = service.courses().courseWork().studentSubmissions().list(
            courseId = course_id,
            courseWorkId = coursework_id,
            pageSize=1,
            # Specify the preview version. Rubrics CRUD capabilities are
            # supported in V1_20231110_PREVIEW and later.
            previewVersion="V1_20231110_PREVIEW"
        ).execute()
        submissions = response.get("studentSubmissions", [])
        if not submissions:
            print(
                """No submissions found. Did you remember to turn in and grade
                   the assignment in the UI?""")
            return
        submission = submissions[0]
        return submission

    except HttpError as error:
        print(f"An error occurred: {error}")
        return error

接著，更新並執行 main.py，即可查看繳交成績。

if __name__ == '__main__':
    service = build_authenticated_service(YOUR_API_KEY)

    submission = get_latest_submission(
        service, YOUR_COURSE_ID, YOUR_COURSEWORK_ID)
    print(json.dumps(submission, indent=4))

draftRubricGrades 和 assignedRubricGrades 包含：

• 相應評分量表標準的 criterionId。
• 老師指派給各項準則的 points。可能來自 但老師也可能覆寫這個設定
• 為各項條件選擇的等級 levelId。如果老師沒有 選擇等級，但仍為該條件指定分數 。

這些清單只包含教師 所選等級或設定分數舉例來說，如果老師選擇 在評分期間與一項條件互動時，draftRubricGrades和 即使評分量表擁有多個項目，assignedRubricGrades 也只會有一個項目 標準。

提示： 建議您趁此機會測試這些屬性。您可以重新評分 以學生身分在 Classroom UI 中重新繳交作業， 切換至老師帳戶，並選擇「清除」，建立新課程 重新發還作業。選取完成後 如要查看學生提交物件的變更，請重新執行 Python 指令碼。

刪除評分量表

您可以透過標準 Delete 要求刪除評分量表。以下程式碼 顯示完整性的函式範例 ，您無法刪除目前的評分量表：

def delete_rubric(service, course_id, coursework_id, rubric_id):
    """Deletes the rubric on a coursework."""
    try:
        service.courses().courseWork().rubrics().delete(
            courseId=course_id,
            courseWorkId=coursework_id,
            id=rubric_id,
            # Specify the preview version. Rubrics CRUD capabilities are
            # supported in V1_20231110_PREVIEW and later.
            previewVersion="V1_20231110_PREVIEW"
        ).execute()

    except HttpError as error:
        print(f"An error occurred: {error}")
        return error

匯出及匯入評分量表

評分量表可以手動匯出至 Google 方便老師重複使用的試算表。

除了在程式碼中指定評分量表條件以外，您也可以建立和 如要從這些匯出的工作表中更新評分量表，請指定 評分量表主體中的 sourceSpreadsheetId，而不是 criteria：

注意： 如要從使用者的試算表建立 (或更新) 評分量表，您的應用程式 必須要求 https://www.googleapis.com/auth/spreadsheets.readonly https://www.googleapis.com/auth/spreadsheets 範圍。做法如下： 如相關章節中所述，將其中一個範圍加入至專案 設定 OAuth 並更新 main.py 中的 SCOPES 變數，使其包含 刪除「token.json」以便使用新範圍重新授權 下次執行 main.py 時。請注意，spreadsheets 範圍是 通常視為敏感資料，因此可能需要完成驗證。

def create_rubric_from_sheet(service, course_id, coursework_id, sheet_id):
    """Creates an example rubric on a coursework."""
    try:
        body = {
            "sourceSpreadsheetId": sheet_id
        }

        rubric = service.courses().courseWork().rubrics().create(
            courseId=course_id, courseWorkId=coursework_id, body=body,
            # Specify the preview version. Rubrics CRUD capabilities are
            # supported in V1_20231110_PREVIEW and later.
            previewVersion="V1_20231110_PREVIEW"
            ).execute()

        print(f"Rubric created with ID {rubric.get('id')}")
        return rubric

    except HttpError as error:
        print(f"An error occurred: {error}")
        return error

意見回饋

如有任何問題或想提供意見，歡迎分享意見回饋。