开始使用评分准则

rubric 是教师在为学生提交的作业评分时可以使用的模板。借助 Classroom API,您可以代表教师管理这些评分标准,还可以读取学生提交的作业的评分标准分数。

Google 课堂界面中的评分准则视图 图 1. Google 课堂作业中的示例评分准则视图。

本指南介绍了 Rubrics API 的基本概念和功能。如需了解评分标准的一般结构以及如何在 Google 课堂界面中进行评分标准评分,请参阅以下帮助中心文章。

前提条件

本指南假定您具备以下各项:

为桌面应用授权凭据

如需以最终用户身份进行身份验证并访问应用中的用户数据,您需要创建一个或多个 OAuth 2.0 客户端 ID。客户端 ID 用于向 Google 的 OAuth 服务器标识单个应用。如果您的应用在多个平台上运行,您必须为每个平台分别创建客户端 ID。

  1. 在 Google Cloud 控制台中,前往 Google Cloud 凭据页面
  2. 依次点击创建凭据 > OAuth 客户端 ID
  3. 依次点击应用类型 > 桌面应用
  4. 名称字段中,输入凭据的名称。此名称仅在 Google Cloud 控制台中显示。例如,“Rubrics client”。
  5. 点击创建。此时会显示“OAuth 客户端已创建”界面,其中显示您的新客户端 ID 和客户端密钥。
  6. 依次点击下载 JSON确定。新创建的凭据会显示在“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 API 的 OAuth 2.0 范围中查看所有 Classroom 范围。

配置示例

在工作目录中,安装 Python 版 Google 客户端库:

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

创建一个名为 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_idcoursework_id。所有评分标准 CRUD 操作都需要这些字段。

您现在应该在 Google 课堂中看到一个示例 CourseWork

Google 课堂界面中的作业视图 图 2. Google 课堂中示例作业的视图。

检查用户资格

如需创建和更新评分标准,提出请求的用户和相应课程的所有者都必须拥有 Google Workspace 教育 Plus 版许可。 Google 课堂支持用户资格条件端点,以便开发者确定用户有权使用的功能。

更新并运行 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:
      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 以创建示例评分标准,使用您之前获得的 CourseCourseWork 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))

以下是有关评分标准表示法的一些说明:

  • 评分标准和等级顺序会反映在 Google 课堂界面中。
  • 有得分的级别(具有 points 属性)必须按积分以升序或降序进行排序(不能随机排序)。
  • 教师可以在界面中重新排序评分标准和评分等级(但不能重新排序未评分等级),这会更改它们在数据中的顺序。

如需了解有关评分标准结构的更多注意事项,请参阅限制

返回到界面后,您应该会在作业中看到评分标准。

Google 课堂界面中的评分准则视图 图 3. Google 课堂作业中的示例评分准则视图。

阅读评分准则

您可以使用标准 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
            ).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. 新标准和级别的顺序被视为新界面顺序(但存在上述限制)。

添加用于更新评分标准的函数:

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 进行修改。

然后修改 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))

现在,教师应该可以在 Google 课堂中看到这些更改。

Google 课堂界面中更新后的评分准则视图 图 4. 更新后的评分标准的视图。

查看使用评分准则评过分的提交内容

目前,API 无法使用评分准则为学生提交的内容评分,但您可以读取在 Google 课堂界面中使用评分准则评过分的提交内容的评分准则分数。

在 Google 课堂界面中,以学生的身份完成并上交示例作业。 然后,作为教师,您可以使用评分标准手动为作业评分

Google 课堂界面中的评分准则得分视图 图 5. 教师在评分期间查看的评分准则。

StudentSubmissions 且已使用评分标准评分的作业新增了两个属性:draftRubricGradesassignedRubricGrades,分别表示教师在草稿和已分配评分状态下选择的分数和等级。

您可以使用现有的 studentSubmissions.get()studentSubmissions.list() 方法来查看已评分的提交内容。

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

draftRubricGradesassignedRubricGrades 包含:

  • 相应评分标准标准的 criterionId
  • 教师为每条评分标准分配的points。这可能来自所选的级别,但教师也可能已覆盖此设置。
  • 为每条评分标准选择的等级的levelId。如果教师未选择等级,但仍为相应标准分配了分数,则此字段不存在。

这些列表仅包含教师选择等级或设置分数的评分标准条目。例如,如果教师在评分期间选择仅与一个评分标准互动,即使评分标准包含多个评分标准,draftRubricGradesassignedRubricGrades 也只会包含一个项目。

删除评分准则

您可以使用标准 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
        ).execute()

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

导出和导入评分标准

评分准则可以手动导出到 Google 表格,供教师重复使用。

除了在代码中指定评分标准之外,还可以通过在评分标准正文中指定 sourceSpreadsheetId 而不是 criteria,从这些导出的工作表中创建和更新评分标准:

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