附件成绩和成绩回传

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

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

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

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

在本演示过程中,您将完成以下操作:

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

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

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

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

您的插件可以为附件设置成绩分子和成绩分母。它们分别使用 API 中的 pointsEarnedmaxPoints 值进行设置。设置 maxPoints 值后,Google 课堂界面中的附件卡片会显示该值。

一个分配具有 maxPoints 的多个连接示例

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

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

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

如果有多个附件设置了 maxPoints,则移除具有“成绩同步”的附件不会为其余任何附件启用“成绩同步”。添加另一个设置了 maxPoints 的附件后,系统会在新附件上启用成绩同步,并调整作业最高成绩以与之匹配。您无法以程序化方式查看哪个附件具有“成绩同步”标签,也无法查看特定作业包含的附件数量。

设置附件的最高成绩

本部分介绍如何为附件成绩设置“分母”;即所有学生在提交时可能获得的最高分数。为此,请设置附件的 maxPoints 值。

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

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

Python

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

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,以在学生提交活动时使用存储的凭据传回成绩。

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

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

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

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

这些因素的结合意味着,教师可能必须完成大量耗时的手动工作才能填充课程的成绩。

如需实现此方法,请向现有的学生作业审核路由再添加一个 API 调用。

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

Python

# 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 课堂界面中填充成绩,从而避免出现上述问题。最终用户会认为评分体验顺畅高效。此外,此方法还可让您选择传回成绩的时刻,例如学生完成活动时或异步返回成绩。

如需实现此方法,请完成以下任务:

  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

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

测试插件

与上一个演示类似,以教师身份创建包含活动类型附件的作业,以学生身份提交回复,然后在“学生作业回顾”iframe 中打开他们提交的作业。您应该会在不同时间看到成绩,具体取决于您的实现方法:

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

确认系统为学生显示正确的分数。

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