開始使用評分量表

rubric 是老師在評分時可以使用的範本。Classroom API 可讓您代表老師管理這些評量表，以及讀取學生提交作業的評量表成績。

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

本指南說明 Rubrics API 的基本概念和功能。如要瞭解評分量表的一般結構，以及如何在 Classroom 使用者介面評分，請參閱這些說明中心文章。

必要條件

本指南假設您已具備下列條件：

• Python 3.8.6 以上版本
• pip 套件管理工具
• Google Cloud 專案。
• 具備已啟用 Google Classroom 的 Google Workspace for Education 帳戶，並獲派 Google Workspace for Education Plus 授權。如果沒有，可以申請升級開發人員試用帳戶。
• 至少有一個測試學生帳戶的測試課程。如果沒有可供測試的 Classroom 課程，請在使用者介面中建立課程，並新增測試學生。

重要事項： 您必須具備 Google Workspace for Education Plus 授權，才能使用 Classroom API 建立及更新評量表，並完成本教學課程。 請參閱使用者資格指南，進一步瞭解如何向使用者公開 API 功能，以及 Classroom API 的必要條件，以便熟悉並申請試用帳戶。

授權電腦應用程式的憑證

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

1. 在 Google Cloud 控制台中，前往 Google Cloud 「憑證」頁面。
2. 依序點選「建立憑證」 >「OAuth 用戶端 ID」。
3. 依序點選「應用程式類型」 >「電腦應用程式」。
4. 在「Name」(名稱) 欄位中，輸入憑證名稱。這個名稱只會顯示在 Google Cloud 控制台中。例如「Rubrics client」。
5. 按一下「建立」，系統會顯示「已建立 OAuth 用戶端」畫面，其中包含新的用戶端 ID 和用戶端密鑰。
6. 依序按一下「下載 JSON」和「確定」。新建立的憑證會顯示在「OAuth 2.0 Client IDs」下方。
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授權範圍範例。如要查看所有 Classroom 範圍，請參閱「Google API 適用的 OAuth 2.0 範圍」。

設定範例

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

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

注意： 本教學課程使用 userProfiles.checkUserCapability() 方法，判斷使用者是否符合使用評量表寫入方法的資格。由於 checkUserCapability() 方法處於開發人員搶先體驗階段，因此標準用戶端程式庫不會公開這個方法。以下範例在產生程式庫時指定 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 指派事項。

提示： 即使老師擁有應用程式，應用程式也無法管理老師在 Classroom 使用者介面中建立的課程作業評分量表。如果這項限制嚴重影響您的用途，請在公開 Issue Tracker 中分享意見回饋。

在 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。所有評量表 CRUD 作業都需要這些權限。

現在 Classroom 中應該會有 CourseWork 範例。

圖 2. Classroom 中的作業範例。

檢查使用者資格

如要建立及更新評量表，提出要求的使用者和相應課程擁有者都必須具備 Google Workspace for Education Plus 授權。Classroom 支援使用者資格端點，可讓開發人員判斷使用者可存取的功能。

更新並執行 main.py，確認測試帳戶可存取評量表功能：

注意： 由於 checkUserCapability() 屬於開發人員預覽版，因此呼叫時必須指定適當的 previewVersion。如要進一步瞭解如何指定版本，請參閱「存取預先發布的 API」一文，如要瞭解支援哪些版本，請參閱「路線圖」。

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

    capability = service.userProfiles().checkUserCapability(
        userId='me',
        # Specify the preview version. checkUserCapability is
        # supported in V1_20240930_PREVIEW and later.
        previewVersion="V1_20240930_PREVIEW",
        capability="CREATE_RUBRIC").execute()

    if not capability.get('allowed'):
      print('User ineligible for rubrics creation.')
      # TODO(developer): in a production app, this signal could be used to
      # proactively hide any rubrics related features from users or encourage
      # them to upgrade to the appropriate license.
    else:
      print('User eligible for rubrics creation.')

建立評分量表

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

您可以在 CourseWork 上建立評分量表，方法是使用包含完整評分量表物件的 create() 呼叫，其中準則和等級的 ID 屬性會省略 (這些屬性會在建立時產生)。

在 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
            ).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)

    capability = service.userProfiles().checkUserCapability(
        userId='me',
        # Specify the preview version. checkUserCapability is
        # supported in V1_20240930_PREVIEW and later.
        previewVersion="V1_20240930_PREVIEW",
        capability="CREATE_RUBRIC").execute()

    if not capability.get('allowed'):
      print('User ineligible for rubrics creation.')
      # TODO(developer): in a production app, this signal could be used to
      # proactively hide any rubrics related features from users or encourage
      # them to upgrade to the appropriate license.
    else:
      rubric = create_rubric(service, YOUR_COURSE_ID, YOUR_COURSEWORK_ID)
      print(json.dumps(rubric, indent=4))

評分量表呈現方式的注意事項：

• Classroom 使用者介面會反映準則和等級順序。
• 有分數的等級 (具有 points 屬性) 必須依分數遞增或遞減排序 (不能隨機排序)。
• 老師可以在使用者介面中重新排序評分標準和評分等級 (但不能重新排序未評分等級)，這會變更資料中的順序。

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

回到使用者介面，您應該會看到作業的評分規準。

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

閱讀評分量表

您可以使用標準的 list() 和 get() 方法讀取評量表。

作業最多只能有一個評分量表，因此 list() 可能看起來不直覺，但如果您還沒有評分量表 ID，這就很有幫助。如果 CourseWork 沒有相關聯的評分標準，list() 回應會是空白。

注意： 只有評量表 create() 和 patch() 方法會受到授權限制，因此這裡不需要進行 checkUserCapability() 檢查。

在 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
            ).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
        ).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'
        ).execute()

        return rubric

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

在本例中，criteria 欄位已指定要使用 updateMask 進行修改。

注意： 更新評量表時，使用者必須符合與建立評量表時相同的資格，因此建議再次使用 checkUserCapability()。

然後修改 main.py，針對上述每項更新規則進行變更：

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

    capability = service.userProfiles().checkUserCapability(
        userId='me',
        # Specify the preview version. checkUserCapability is
        # supported in V1_20240930_PREVIEW and later.
        previewVersion="V1_20240930_PREVIEW",
        capability="CREATE_RUBRIC").execute()

    if not capability.get('allowed'):
      print('User ineligible for rubrics creation.')
      # TODO(developer): in a production app, this signal could be used to
      # proactively hide any rubrics related features from users or encourage
      # them to upgrade to the appropriate license.
    else:
        # 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 使用者介面中的學生，請完成並繳交範例作業。 接著，老師可以使用評分量表手動批改作業。

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

提示： 建議您趁這個機會熟悉老師使用評量表時的彈性。舉例來說，老師可以覆寫所選等級的準則分數、根據準則計算的作業總分，以及完全略過選擇等級。詳情請參閱「限制」一節。

StudentSubmissions 評分表評分的作業有兩個新屬性：draftRubricGrades 和 assignedRubricGrades，分別代表老師在草稿和指派評分狀態期間選擇的分數和等級。

您可以使用現有的 studentSubmissions.get() 和 studentSubmissions.list() 方法，查看已評分的提交內容。

注意： 這些studentSubmissions欄位沒有資格限制。

在 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
        ).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 使用者介面中以學生身分重新繳交作業，然後切換至老師帳戶並選擇「清除」，重新選取選項並重新發還作業。完成後，您可以重新執行 Python 指令碼，查看學生提交的物件變更。

刪除評分量表

您可以使用標準 delete() 要求刪除評量表。以下程式碼是完整性的函式範例，但由於評分作業已開始，因此您無法刪除目前的評分量表：

注意： 刪除評量表時，使用者資格必須與建立評量表時相同，因此建議在正式環境中使用 checkUserCapability()。

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

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

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