附件成绩和成绩回传

这是关于 Google 课堂插件的第六个演示 演示系列视频

在本演示中，您将修改上一个演示步骤中的示例 来生成已评分的活动类型附件。您还发回了成绩 以编程方式上传到 Google 课堂，这些信息会显示在教师的成绩中 将图书保存为草稿成绩。

本演示与系列中的其他演示略有不同， 介绍了两种可能的方法将成绩传回 课堂。两者对开发者和用户有着截然不同的影响 体验；在设计 Google 课堂插件时，请考虑这两种情况。 请阅读我们的“与附件交互”指南页面， 实现选项。

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

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

• 将之前的附件创建请求修改为 Classroom API 还可设置附件的成绩分母。
• 以编程方式为学生提交的作业评分，并设置附件的 成绩分子。
• 采用两种方法将作业的成绩传递给 使用已登录或离线教师凭据的 Google 课堂。

完成后，成绩会显示在“课堂”成绩册中， 就会触发回传行为这种情况发生的确切时间取决于 实施方法。

在本示例中，重复使用上一个 activity 中的 activity 视频中，学生会看到著名地标的图片， 系统提示用户输入其名称如果学生符合以下条件，请为附件分配满分： 输入正确的名称，否则输入 0。

重要提示 ：在按照本演示操作之前，请先完成之前的演示 系列中的其他视频本演示扩展了上一节课中开发的 Web 应用 演示。您可以下载所有演示的完整源代码 “概览”页此演示的代码可以在 /06-grade-passback/ 目录下。

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

您的插件可以为 附件。它们分别使用 pointsEarned 和 maxPoints 进行设置 值。Google 课堂界面中的附件卡片显示了 maxPoints 值（如果设置了该值）。

图 1. 作业创建界面，其中显示了三张插件附件卡片， 设置了 maxPoints。

借助 Classroom 插件 API，您可以配置和使用 附件成绩的得分。这些与 作业的成绩。不过，作业成绩设置遵循的是 针对已启用成绩同步标签的附件的附件成绩设置 附件卡片。当系统显示“成绩同步”将 pointsEarned 的附件设置为 学生提交作业时，系统还会设置学生的作业初始成绩。

通常情况下，添加到作业中的第一个附件将设置 maxPoints 会收到“成绩同步”标签。查看作业创建界面 图 1 所示的“成绩同步”示例标签。请注意， “附件 1”“成绩同步”卡片标签和作业成绩 已更新为 50 分。另请注意，虽然图 1 显示了三张附件卡片，只有一张卡片具有“成绩同步”标签。这是 当前实施的一个关键限制：一个附件只能有 “成绩同步”标签。

重要提示 ：只有一个附件可以同步“成绩”标签。我们建议 务必明确告知教师，如果教师添加更多 一个支持成绩回传的附件。

如果有多个附件设置了 maxPoints，请移除 带有“成绩同步”的附件不会启用“成绩同步”在任意 剩余附件。添加其他设置 maxPoints 的附件会启用 系统会同步新附件的成绩，作业最高成绩将调整为 匹配。没有以编程方式查看哪个附件具有 “成绩同步”标签，也可以查看特定分配关系包含多少个附件。

设置附件的最高成绩

本部分介绍如何为附件成绩设置“分母”；那个 是指所有学生都能在各自的 提交内容。为此，请设置附件的 maxPoints 值。

只需对现有实施稍作修改即可启用 以及评分功能创建附件时，将 maxPoints 值添加到 同一个包含 studentWorkReviewUri 的 AddOnAttachment 对象， teacherViewUri 和其他附件字段。

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

Python

在构建 attachment 对象时添加 maxPoints 字段，只需 然后再向CREATE courses.courseWork.addOnAttachments 端点。您可以在 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 值存储在 您的本地附件数据库；因此无需进行额外的 API 调用 以便日后对学生提交的作业进行评分但请注意 教师可以独立于插件更改作业成绩设置。发送 向 courses.courseWork 端点发出 GET 请求，以查看 maxPoints 值。执行此操作时，请将 itemId 传入 CourseWork.id 字段。

现在，更新您的数据库模型，以同时保存附件的 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

在顶部找到 SET_GRADE_WITH_LOGGED_IN_USER_CREDENTIALS 声明 共 webapp/attachment_routes.py 个文件。将此值设置为 True 即可回传 使用已登录教师的凭据进行评分。将此值设置为 False 在学生提交 活动。

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

注意 ：这种设置成绩的方法虽然更易于实现，但 对教师用户体验的显著影响。Google 的 用户体验研究表明，最终不应首选这种方法 用户。有教师报告称，某个插件已损坏或 告诉他们是在以某种方式不当使用应用的

阅读此内容和以下内容 部分内容，然后再决定实现方法。

使用已登录用户的凭据发出设置 pointsEarned 的请求。 这看起来应该非常直观，因为它反映了我们的 几乎不费力就可以实现

但请注意，教师只与学生的课程互动。 学生作业回顾 iframe 中提交的内容。其中有一些重要的 影响：

• 在教师参加前，Google 课堂中不会填充任何成绩 操作。
• 教师可能需要打开学生提交的每项内容， 学生成绩。
• Google 课堂收到成绩后会有短暂的延迟 及其在 Google 课堂界面中的外观。延迟时间为 通常为 5 到 10 秒，但最长可长达 30 秒。

这些因素结合在一起，就意味着教师 填充课程的成绩所需的大量耗时的手动工作。

注意 ：一种可能的改进方法是，在教师向教师提问时 查看特定附件的任意一项提交内容。不过，这可能无法 必须解决相应问题，并且可能需要大量计算开销；考虑 首次触发时，系统可能只会显示部分学生成绩， 让教师打开多个提交的内容以完整填充成绩册

自动传递成绩的替代方案是提供 “回传所有”按钮。 这样，教师就可以控制何时填充成绩册 仍然需要教师手动操作。

如需实现此方法，请向现有 Student 额外添加一个 API 调用 “工作审核”路由。

提取学生提交内容和附件记录后，请评估 并存储最终成绩。在 AddOnAttachmentStudentSubmission 对象的 pointsEarned 字段。最后， 将PATCH请求发送到 courses.courseWork.addOnAttachments.studentSubmissions 端点， AddOnAttachmentStudentSubmission 实例。请注意， 还需要在 PATCH 请求的 updateMask 中指定 pointsEarned：

Python

注意 ：在我们提供的 Python 示例中，将 SET_GRADE_WITH_LOGGED_IN_USER_CREDENTIALS 至 True 英寸 webapp/attachment_routes.py 使用此方法运行示例。

# 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 Identity 实现指南页面 了解有关请求离线令牌的更多信息。

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

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

在本演示中，请在学生完成时设置成绩 相应活动；也就是说，学生在“学生视图”中提交表单 。

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

要进行 API 调用，需要两个唯一的令牌：刷新令牌和 访问令牌。如果您到目前为止一直在按演示系列视频进行操作， User 表架构应已存储刷新令牌。存储刷新 令牌就足够了， 您在身份验证流程中会收到一个访问令牌。

但是，您现在需要以 表示身份验证流程不可用。因此，您需要存储 访问令牌和刷新令牌将 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()

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

要为活动设置成绩，请调用将 pointsEarned 设置为 教师。您可以通过以下几种方法完成此操作：

• 存储教师凭据与课程 ID 的本地映射。但请注意 同一位教师未必总会与某门课程相关联。
• 向 Classroom API courses 端点发出 GET 个请求，以 获取当前教师。然后，查询本地用户记录以查找 匹配的教师凭据。
• 创建插件附件时，请将教师 ID 存储在本地 附件数据库。然后，从 attachmentId 传递给了学生视图 iframe。

此示例展示了最后一个选项， 学生完成活动附件。

将教师 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

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

# 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

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

# 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 示例中，将 SET_GRADE_WITH_LOGGED_IN_USER_CREDENTIALS 至 False 英寸 webapp/attachment_routes.py 使用此方法运行示例。

# 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 课堂之外。