附件成绩和成绩回传

这是 Google 课堂插件演示系列的第 6 个演示。

在本演示文稿中，您将修改上一个演示文稿步骤中的示例，以生成评分的活动类型附件。您还可以通过编程方式将成绩传回 Google 课堂，该成绩会在教师的成绩册中显示为草稿成绩。

本演示文稿与本系列中的其他演示文稿略有不同，因为目前有两种可能的方法可以将成绩传回 Google 课堂。这两种方式对开发者和用户体验有不同的影响；在设计 Google 课堂插件时，请同时考虑这两种方式。如需详细了解实现选项，请参阅我们的“与附件互动”指南页面。

请注意，API 中的评分功能是可选的。它们可与任何活动类型的附件搭配使用。

在本演示过程中，您将完成以下操作：

• 修改之前向 Google 课堂 API 发出的附件创建请求，以便同时设置附件的成绩分母。
• 以编程方式为学生提交的作业评分，并设置附件的成绩分子。
• 实现两种方法，以便使用已登录的教师凭据或离线教师凭据将提交内容的分数传递给 Google 课堂。

完成后，在触发回传行为后，成绩会显示在 Google 课堂成绩册中。具体发生时间取决于实现方法。

在本例中，我们将重复使用上一个演示中的 activity，其中向学生显示著名地标的图片，并提示学生输入地标的名称。如果学生输入的名称正确，则为附件分配满分，否则为零分。

重要提示： 在按照本演示文稿操作之前，请先完成本系列中的前面演示文稿。本演示文稿将扩展前面演示文稿中开发的 Web 应用。您可以从“概览”页面下载所有演示文稿的完整源代码。您可以在 /06-grade-passback/ 目录中找到此特定演示文稿的代码。

了解 Google 课堂插件 API 评分功能

您的插件可以为附件设置分子和分母。这些值分别使用 API 中的 pointsEarned 和 maxPoints 值进行设置。设置 maxPoints 值后，Google 课堂界面中的附件卡片会显示该值。

图 1. 作业创建界面，其中包含三个已设置 maxPoints 的插件附件卡片。

借助 Google 课堂插件 API，您可以配置附件成绩的设置并设置所得分数。这些成绩与作业成绩不同。不过，作业成绩设置会遵循附件卡片上带有成绩同步标签的附件的成绩设置。当“成绩同步”附件为学生提交的作业设置 pointsEarned 时，它还会为作业设置学生的草稿成绩。

通常，添加到设置了 maxPoints 的作业中的第一个附件会收到“成绩同步”标签。如需查看“成绩同步”标签的示例，请参阅图 1 中显示的作业创建界面示例。请注意，“附件 1”卡片带有“成绩同步”标签，并且红色框中的作业成绩已更新为 50 分。另请注意，虽然图 1 显示了三张附件卡片，但只有一张卡片带有“成绩同步”标签。这是当前实现的一个关键限制：只有一个附件可以带有“成绩同步”标签。

重要提示 ：只有一个附件可以带有“成绩同步”标签。如果教师添加了多个支持成绩回传的附件，建议您明确告知教师预期行为。

如果有多个附件设置了 maxPoints，则移除具有“成绩同步”的附件不会为其余任何附件启用“成绩同步”。添加另一个设置了 maxPoints 的附件后，系统会在新附件上启用成绩同步，并调整作业最高成绩以匹配。没有任何机制可以以编程方式查看哪些附件带有“成绩同步”标签，也无法查看特定作业有多少附件。

设置附件的最高成绩

本部分介绍了如何为附件成绩设置分母，即所有学生可以通过提交内容获得的最高分数。为此，请设置附件的 maxPoints 值。

只需对现有实现进行细微修改，即可启用评分功能。创建附件时，请在包含 studentWorkReviewUri、teacherViewUri 和其他附件字段的同一 AddOnAttachment 对象中添加 maxPoints 值。

请注意，新作业的默认满分为 100 分。我们建议您将 maxPoints 设置为 100 以外的值，以便您验证成绩是否设置正确。为演示目的，将 maxPoints 设置为 50：

Python

在构建 attachment 对象时添加 maxPoints 字段，紧接着向 courses.courseWork.addOnAttachments 端点发出 CREATE 请求。如果您按照我们提供的示例操作，则可以在 webapp/attachment_routes.py 文件中找到此值。

attachment = {
    # Specifies the route for a teacher user.
    "teacherViewUri": {
        "uri":
            flask.url_for(
                "load_activity_attachment",
                _scheme='https',
                _external=True),
    },
    # Specifies the route for a student user.
    "studentViewUri": {
        "uri":
            flask.url_for(
                "load_activity_attachment",
                _scheme='https',
                _external=True)
    },
    # Specifies the route for a teacher user when the attachment is
    # loaded in the Classroom grading view.
    "studentWorkReviewUri": {
        "uri":
            flask.url_for(
                "view_submission", _scheme='https', _external=True)
    },
    # Sets the maximum points that a student can earn for this activity.
    # This is the denominator in a fractional representation of a grade.
    "maxPoints": 50,
    # The title of the attachment.
    "title": f"Attachment {attachment_count}",
}

在此演示中，您还将 maxPoints 值存储在本地 Attachment 数据库中；这样，您日后在评分学生提交的内容时就不必再进行额外的 API 调用。不过，请注意，教师可能会独立于您的插件来更改作业成绩设置。向 courses.courseWork 端点发送 GET 请求，以查看作业级 maxPoints 值。执行此操作时，请在 CourseWork.id 字段中传递 itemId。

现在，更新数据库模型，使其也包含附件的 maxPoints 值。我们建议您使用 CREATE 响应中的 maxPoints 值：

Python

首先，向 Attachment 表添加 max_points 字段。如果您按照我们提供的示例操作，则可以在 webapp/models.py 文件中找到此值。

# Database model to represent an attachment.
class Attachment(db.Model):
    # The attachmentId is the unique identifier for the attachment.
    attachment_id = db.Column(db.String(120), primary_key=True)

    # The image filename to store.
    image_filename = db.Column(db.String(120))

    # The image caption to store.
    image_caption = db.Column(db.String(120))

    # The maximum number of points for this activity.
    max_points = db.Column(db.Integer)

返回 courses.courseWork.addOnAttachments CREATE 请求。存储响应中返回的 maxPoints 值。

new_attachment = Attachment(
    # The new attachment's unique ID, returned in the CREATE response.
    attachment_id=resp.get("id"),
    image_filename=key,
    image_caption=value,
    # Store the maxPoints value returned in the response.
    max_points=int(resp.get("maxPoints")))
db.session.add(new_attachment)
db.session.commit()

附件现在具有最高分数。现在，您应该能够测试此行为了；为新作业添加附件，然后观察附件卡片显示“成绩同步”标签，以及作业的“分数”值发生变化。

在 Google 课堂中为学生提交的内容设置成绩

本部分介绍了如何为附件成绩设置分子，即单个学生的附件成绩。为此，请设置学生提交内容的 pointsEarned 值。

现在，您需要做出一项重要的决定：您的插件应如何发出设置 pointsEarned 的请求？

问题在于，设置 pointsEarned 需要 teacher OAuth 范围。您不应向学生用户授予 teacher 作用域；否则，当学生与您的插件互动时，可能会出现意外行为，例如加载教师视图 iframe 而非学生视图 iframe。因此，您可以通过以下两种方式设置 pointsEarned：

• 使用已登录教师的凭据。
• 使用存储的（离线）教师凭据。

以下各部分将先讨论每种方法的权衡，然后再演示每种实现。请注意，我们提供的示例演示了将成绩传递给 Google 课堂的两种方法；请参阅下方针对不同语言的说明，了解如何在运行提供的示例时选择方法：

Python

在 webapp/attachment_routes.py 文件顶部找到 SET_GRADE_WITH_LOGGED_IN_USER_CREDENTIALS 声明。将此值设为 True 可使用已登录教师的凭据传回成绩。将此值设置为 False，以便在学生提交作业时使用存储的凭据传回成绩。

使用已登录教师的凭据设置成绩

注意 ：虽然这种评分方法更易于实现，但会对教师用户体验产生明显影响。Google 用户体验研究收集的反馈表明，最终用户不喜欢这种方法。有教师反映，他们认为某个插件“已损坏”或他们在使用方面存在某种错误。

在决定实现方法之前，请仔细阅读本部分及以下部分。

使用已登录用户的凭据发出设置 pointsEarned 的请求。这应该非常直观，因为它反映了到目前为止的实现的其余部分，并且实现起来几乎不需要任何努力。

不过，请注意，教师只能在“学生作业评价”iframe 中与学生提交的作业互动。这具有一些重要意义：

• 在教师在 Google 课堂界面中采取行动之前，Google 课堂中不会填充任何成绩。
• 教师可能必须打开每个学生提交的作业，才能填充所有学生的成绩。
• 在 Google 课堂收到成绩与成绩显示在 Google 课堂界面之间会有一个短暂的延迟。延迟时间通常为 5 到 10 秒，但最长可能达到 30 秒。

这些因素综合起来意味着，教师可能必须进行大量耗时的手动工作，才能完整填充一门课程的成绩。

注意 ：一个可能的改进是，当教师查看特定附件的任何提交内容时，系统会回传所有学生成绩。不过，这不一定能解决问题，并且计算开销可能很高；请考虑到，首次触发时可能并非所有学生的成绩都已可用，因此教师无论如何都需要打开多个提交内容才能完全填充成绩册。

自动传递成绩的替代方案是在“学生作业评阅”或“教师视图”iframe 中提供“全部传回”按钮。这样，教师就可以控制成绩册何时填充，但仍需要教师手动执行操作。

如需实现此方法，请在现有的学生作业评价路线中再添加一个 API 调用。

提取学生提交的内容和附件记录后，评估学生提交的内容并存储得出的成绩。在 AddOnAttachmentStudentSubmission 对象的 pointsEarned 字段中设置成绩。最后，向 courses.courseWork.addOnAttachments.studentSubmissions 端点发出 PATCH 请求，并在请求正文中添加 AddOnAttachmentStudentSubmission 实例。请注意，我们还需要在 PATCH 请求的 updateMask 中指定 pointsEarned：

Python

注意 ：在我们提供的 Python 示例中，请在 webapp/attachment_routes.py 中将 SET_GRADE_WITH_LOGGED_IN_USER_CREDENTIALS 设置为 True，以便使用此方法运行示例。

# Look up the student's submission in our database.
student_submission = Submission.query.get(flask.session["submissionId"])

# Look up the attachment in the database.
attachment = Attachment.query.get(student_submission.attachment_id)

grade = 0

# See if the student response matches the stored name.
if student_submission.student_response.lower(
) == attachment.image_caption.lower():
    grade = attachment.max_points

# Create an instance of the Classroom service.
classroom_service = ch._credential_handler.get_classroom_service()

# Build an AddOnAttachmentStudentSubmission instance.
add_on_attachment_student_submission = {
    # Specifies the student's score for this attachment.
    "pointsEarned": grade,
}

# Issue a PATCH request to set the grade numerator for this attachment.
patch_grade_response = classroom_service.courses().courseWork(
).addOnAttachments().studentSubmissions().patch(
    courseId=flask.session["courseId"],
    itemId=flask.session["itemId"],
    attachmentId=flask.session["attachmentId"],
    submissionId=flask.session["submissionId"],
    # updateMask is a list of fields being modified.
    updateMask="pointsEarned",
    body=add_on_attachment_student_submission).execute()

使用离线教师凭据设置成绩

要点 ：与上一种方法相比，这种方法可显著提升用户体验，但需要完成更多实现工作。我们强烈建议您使用此方法设置成绩。

在确定实现方法之前，请仔细阅读本部分和前面的部分。

若要使用第二种评分方法，则需要使用创建附件的教师的存储凭据。此实现要求您使用之前授权的教师的刷新令牌和访问令牌构建凭据，然后使用这些凭据设置 pointsEarned。

这种方法的一个重要优势是，无需教师执行任何操作即可在 Google 课堂界面中填充成绩，从而避免出现上述问题。最终用户因此会认为评分体验顺畅高效。此外，通过这种方法，您可以选择返回成绩的时机，例如在学生完成活动时或异步返回。

重要提示： 在继续操作之前，请确保您在授权用户时请求的是离线令牌。如需详细了解如何请求离线令牌，请参阅“让用户登录”演示文稿和 Google Identity 实现指南页面。

如需实现此方法，请完成以下任务：

1. 修改“用户”数据库记录以存储访问令牌。
2. 修改 Attachment 数据库记录以存储教师 ID。
3. 检索教师的凭据，并（可选）构建新的 Google 课堂服务实例。
4. 为提交内容设置成绩。

在本演示中，请在学生完成活动（即在学生视图路线中提交表单）时设置成绩。

修改“用户”数据库记录以存储访问令牌

进行 API 调用需要两个唯一令牌，即刷新令牌和访问令牌。如果您一直在按照本演示系列操作，您的 User 表架构应该已存储刷新令牌。如果您仅使用已登录的用户进行 API 调用，则只需存储刷新令牌即可，因为您会在身份验证流程中收到访问令牌。

不过，您现在需要以已登录用户以外的身份进行调用，这意味着身份验证流程不可用。因此，您需要将访问令牌与刷新令牌一起存储。更新 User 表架构以添加访问令牌：

Python

在我们提供的示例中，此值位于 webapp/models.py 文件中。

# Database model to represent a user.
class User(db.Model):
    # The user's identifying information:
    id = db.Column(db.String(120), primary_key=True)
    display_name = db.Column(db.String(80))
    email = db.Column(db.String(120), unique=True)
    portrait_url = db.Column(db.Text())

    # The user's refresh token, which will be used to obtain an access token.
    # Note that refresh tokens will become invalid if:
    # - The refresh token has not been used for six months.
    # - The user revokes your app's access permissions.
    # - The user changes passwords.
    # - The user belongs to a Google Cloud organization
    #   that has session control policies in effect.
    refresh_token = db.Column(db.Text())

    # An access token for this user.
    access_token = db.Column(db.Text())

然后，更新用于创建或更新 User 记录的所有代码，以便同时存储访问令牌：

Python

在我们提供的示例中，此值位于 webapp/credential_handler.py 文件中。

def save_credentials_to_storage(self, credentials):
    # Issue a request for the user's profile details.
    user_info_service = googleapiclient.discovery.build(
        serviceName="oauth2", version="v2", credentials=credentials)
    user_info = user_info_service.userinfo().get().execute()
    flask.session["username"] = user_info.get("name")
    flask.session["login_hint"] = user_info.get("id")

    # See if we have any stored credentials for this user. If they have used
    # the add-on before, we should have received login_hint in the query
    # parameters.
    existing_user = self.get_credentials_from_storage(user_info.get("id"))

    # If we do have stored credentials, update the database.
    if existing_user:
        if user_info:
            existing_user.id = user_info.get("id")
            existing_user.display_name = user_info.get("name")
            existing_user.email = user_info.get("email")
            existing_user.portrait_url = user_info.get("picture")

        if credentials and credentials.refresh_token is not None:
            existing_user.refresh_token = credentials.refresh_token
            # Update the access token.
            existing_user.access_token = credentials.token

    # If not, this must be a new user, so add a new entry to the database.
    else:
        new_user = User(
            id=user_info.get("id"),
            display_name=user_info.get("name"),
            email=user_info.get("email"),
            portrait_url=user_info.get("picture"),
            refresh_token=credentials.refresh_token,
            # Store the access token as well.
            access_token=credentials.token)

        db.session.add(new_user)

    db.session.commit()

修改 Attachment 数据库记录以存储教师 ID

如需为活动设置成绩，请调用以将 pointsEarned 设置为课程教师。您可以通过以下几种方式来实现此目的：

• 存储教师凭据与课程 ID 的本地映射。不过请注意，同一教师可能并不总是与特定课程相关联。
• 向 Classroom API courses 端点发出 GET 请求，以获取当前教师。然后，查询本地用户记录以查找匹配的教师凭据。
• 创建插件附件时，请将教师 ID 存储在本地附件数据库中。然后，从传递给“学生视图”iframe 的 attachmentId 中检索教师凭据。

此示例演示了最后一个选项，因为您是在学生完成活动附件后设置成绩。

将教师 ID 字段添加到数据库的 Attachment 表中：

Python

在我们提供的示例中，此值位于 webapp/models.py 文件中。

# Database model to represent an attachment.
class Attachment(db.Model):
    # The attachmentId is the unique identifier for the attachment.
    attachment_id = db.Column(db.String(120), primary_key=True)

    # The image filename to store.
    image_filename = db.Column(db.String(120))

    # The image caption to store.
    image_caption = db.Column(db.String(120))

    # The maximum number of points for this activity.
    max_points = db.Column(db.Integer)

    # The ID of the teacher that created the attachment.
    teacher_id = db.Column(db.String(120))

然后，更新用于创建或更新 Attachment 记录的所有代码，以便同时存储创建者的 ID：

Python

在我们提供的示例中，此方法位于 webapp/attachment_routes.py 文件中的 create_attachments 方法中。

# Store the attachment by id.
new_attachment = Attachment(
    # The new attachment's unique ID, returned in the CREATE response.
    attachment_id=resp.get("id"),
    image_filename=key,
    image_caption=value,
    max_points=int(resp.get("maxPoints")),
    teacher_id=flask.session["login_hint"])
db.session.add(new_attachment)
db.session.commit()

检索教师的凭据

找到用于提供学生视图 iframe 的路由。将学生的回答存储在本地数据库中后，立即从本地存储空间检索教师的凭据。鉴于前两个步骤中的准备工作，这应该很简单。您还可以使用这些信息为教师用户构建 Google 课堂服务的新实例：

Python

在我们提供的示例中，此方法位于 webapp/attachment_routes.py 文件中的 load_activity_attachment 方法中。

# Create an instance of the Classroom service using the tokens for the
# teacher that created the attachment.

# We're assuming that there are already credentials in the session, which
# should be true given that we are adding this within the Student View
# route; we must have had valid credentials for the student to reach this
# point. The student credentials will be valid to construct a Classroom
# service for another user except for the tokens.
if not flask.session.get("credentials"):
    raise ValueError(
        "No credentials found in session for the requested user.")

# Make a copy of the student credentials so we don't modify the original.
teacher_credentials_dict = deepcopy(flask.session.get("credentials"))

# Retrieve the requested user's stored record.
teacher_record = User.query.get(attachment.teacher_id)

# Apply the user's tokens to the copied credentials.
teacher_credentials_dict["refresh_token"] = teacher_record.refresh_token
teacher_credentials_dict["token"] = teacher_record.access_token

# Construct a temporary credentials object.
teacher_credentials = google.oauth2.credentials.Credentials(
    **teacher_credentials_dict)

# Refresh the credentials if necessary; we don't know when this teacher last
# made a call.
if teacher_credentials.expired:
    teacher_credentials.refresh(Request())

# Request the Classroom service for the specified user.
teacher_classroom_service = googleapiclient.discovery.build(
    serviceName=CLASSROOM_API_SERVICE_NAME,
    version=CLASSROOM_API_VERSION,
    credentials=teacher_credentials)

为提交内容设置成绩

接下来的步骤与使用已登录教师的凭据相同。不过，请注意，您应使用在上一步中检索到的教师凭据进行调用：

Python

注意 ：在我们提供的 Python 示例中，请在 webapp/attachment_routes.py 中将 SET_GRADE_WITH_LOGGED_IN_USER_CREDENTIALS 设置为 False，以便使用此方法运行该示例。

# Issue a PATCH request as the teacher to set the grade numerator for this
# attachment.
patch_grade_response = teacher_classroom_service.courses().courseWork(
).addOnAttachments().studentSubmissions().patch(
    courseId=flask.session["courseId"],
    itemId=flask.session["itemId"],
    attachmentId=flask.session["attachmentId"],
    submissionId=flask.session["submissionId"],
    # updateMask is a list of fields being modified.
    updateMask="pointsEarned",
    body=add_on_attachment_student_submission).execute()

测试插件

重要提示： 在开发阶段，您只能在 Google 课堂插件 iframe 中测试应用。如需了解每个 iframe 的说明，请参阅我们的iframe 和查询参数指南页面。本演示文稿中提供的所有说明均假定该插件可在 iframe 上下文中使用。

与上一个演示步骤类似，以教师身份创建包含活动类型附件的作业，以学生身份提交回答，然后在“学生作业评价”iframe 中打开其提交的内容。您应该会在不同时间看到成绩，具体取决于您的实现方法：

• 如果您在学生完成活动时选择了发回成绩，那么在打开“学生作业评价”iframe 之前，您应该已经在界面中看到了学生的草稿成绩。您还可以在打开作业时在学生列表中看到该信息，以及在“学生作业评价”iframe 旁边的“成绩”框中看到该信息。
• 如果您选择在教师打开“学生作业评价”iframe 时传回成绩，该成绩应该会在 iframe 加载后立即显示在“成绩”框中。如上文所述，此过程最多可能需要 30 秒。之后，特定学生的成绩也应显示在其他 Google 课堂成绩册视图中。

确认学生的成绩是否正确显示。

恭喜！您可以继续执行下一步：在 Google 课堂之外创建附件。