管理课业

Google 课堂提供五种课业类型：作业、测验作业、题目（简答题和选择题）和资料。Classroom API 目前允许开发者读取和写入三种类型：作业、题目和资料。

如需使用此功能，您可以使用 CourseWork 资源，它代表已分配给特定课程的学生的作业或题目，包括任何其他资料和详细信息，如截止日期或最高分数。

除了 CourseWork 资源之外，您还可以使用 StudentSubmission 资源管理已完成的作业。下面几部分详细介绍了相关信息。

创建作业

只能代表课程的教师创建作业，尝试代表学生在课程中创建作业将导致 403 PERMISSION_DENIED 错误。同样，网域管理员也无法为他们不教授的课程创建作业，尝试通过 API 创建课程也会导致 403 PERMISSION_DENIED 错误。

创建分配时，您可以用 materials 形式附加链接，如以下示例代码所示：

Python

classroom/snippets/classroom_create_coursework.py

在 GitHub 上查看

from __future__ import print_function

import google.auth
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError


def classroom_create_coursework(course_id):

    """
    Creates the coursework the user has access to.
    Load pre-authorized user credentials from the environment.
    TODO(developer) - See https://developers.google.com/identity
    for guides on implementing OAuth2 for the application.\n"
    """

    creds, _ = google.auth.default()
    # pylint: disable=maybe-no-member

    try:
        service = build('classroom', 'v1', credentials=creds)
        coursework = {
            'title': 'Ant colonies',
            'description': '''Read the article about ant colonies
                              and complete the quiz.''',
            'materials': [
                {'link': {'url': 'http://example.com/ant-colonies'}},
                {'link': {'url': 'http://example.com/ant-quiz'}}
            ],
            'workType': 'ASSIGNMENT',
            'state': 'PUBLISHED',
        }
        coursework = service.courses().courseWork().create(
            courseId=course_id, body=coursework).execute()
        print(f"Assignment created with ID {coursework.get('id')}")
        return coursework

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


if __name__ == '__main__':
    # Put the course_id of course whose coursework needs to be created,
    # the user has access to.
    classroom_create_coursework(453686957652)

结果包含服务器分配的标识符，可用于在其他 API 请求中引用分配。

title 和 workType 字段是必填字段。其他所有字段均为可选字段。如果未指定 state，系统将创建草稿分配。

要在通过 Classroom API 创建的作业中添加链接的资料，请使用链接资源指定目标网址。Google 课堂会自动获取标题和缩略图。 Classroom API 本身也支持云端硬盘和 YouTube 资料，两者可通过类似的方式添加到 DriveFile 资源或 YouTubeVideo 资源中。

如需指定截止日期，请将 dueDate 和 dueTime 字段设置为相应的世界协调时间 (UTC)。截止日期必须是将来的日期。

检索作业和题目

您可以检索相应课程的学生和教师的作业和题目，或由网域管理员检索。要检索特定的作业或题目，请使用 course.courseWork.get。要检索所有作业或题目（可以选择匹配某些条件），请使用 courses.courseWork.list。

如果您只对某些字段感兴趣，请考虑将请求限制在这些字段。这样可以显著加快处理您请求的速度。如需了解详情，请参阅使用部分资源。

所需范围取决于发出请求的用户在课程中的角色。如果用户是学生，请使用以下范围之一：

• https://www.googleapis.com/auth/classroom.coursework.me.readonly
• https://www.googleapis.com/auth/classroom.coursework.me

如果用户是教师或网域管理员，请使用以下范围之一：

• https://www.googleapis.com/auth/classroom.coursework.students.readonly
• https://www.googleapis.com/auth/classroom.coursework.students

拥有检索作业或题目的权限并不意味着有权访问资料或资料元数据。实际上，这意味着，如果管理员不是课程成员，则可能不会看到附加的云端硬盘文件的标题。如果您想允许管理员访问用户文件，请参阅全网域授权指南。

管理学生的回复

StudentSubmission 资源表示学生完成作业或题目的作业和成绩。创建新问题或作业时，系统会为每个学生隐式创建 StudentSubmission 资源。

学生提交的内容只能由创建相应 CourseWork 资源的 开发者控制台项目修改。除了检查请求的用户是否拥有正确的权限之外，该项目中的任何 OAuth2 客户端都可以进行修改；associatedWithDeveloper 字段指示当前的 OAuth2 客户端是否可以修改给定的 StudentSubmission。

以下部分介绍了管理学生回答的常见操作。

检索学生回复

学生可以检索自己的提交内容，教师可以检索其课程中所有学生的提交内容，而网域管理员可以检索其网域内的所有学生提交的所有内容。每个提交的学生都会分配一个标识符。如果您知道该标识符，请使用 courses.courseWork.studentSubmissions.get 进行检索。

使用 course.stworkentSubmissions.list 获取与某些条件匹配的 StudentSubmission，如以下示例所示：

Python

classroom/snippets/classroom_list_submissions.py

在 GitHub 上查看

from __future__ import print_function

import google.auth
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError


def classroom_list_submissions(course_id, coursework_id):
    """
    Creates the courses the user has access to.
    Load pre-authorized user credentials from the environment.
    TODO(developer) - See https://developers.google.com/identity
    for guides on implementing OAuth2 for the application.\n"
    """

    creds, _ = google.auth.default()
    # pylint: disable=maybe-no-member
    submissions = []
    page_token = None

    try:
        service = build('classroom', 'v1', credentials=creds)
        while True:
            coursework = service.courses().courseWork()
            response = coursework.studentSubmissions().list(
                pageToken=page_token,
                courseId=course_id,
                courseWorkId=coursework_id,
                pageSize=10).execute()
            submissions.extend(response.get('studentSubmissions', []))
            page_token = response.get('nextPageToken', None)
            if not page_token:
                break

        if not submissions:
            print('No student submissions found.')

        print('Student Submissions:')
        for submission in submissions:
            print(f"Submitted at:"
                  f"{(submission.get('id'), submission.get('creationTime'))}")

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


if __name__ == '__main__':
    # Put the course_id and coursework_id of course whose list needs to be
    # submitted.
    classroom_list_submissions(453686957652, 466086979658)

通过指定 userId 参数来检索属于特定学生的学生提交内容，如下例所示：

Python

classroom/snippets/classroom_list_student_submissions.py

在 GitHub 上查看

from __future__ import print_function

import google.auth
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError


def classroom_list_student_submissions(course_id, coursework_id, user_id):
    """
    Creates the courses the user has access to.
    Load pre-authorized user credentials from the environment.
    TODO(developer) - See https://developers.google.com/identity
    for guides on implementing OAuth2 for the application.\n"
    """

    creds, _ = google.auth.default()
    # pylint: disable=maybe-no-member
    submissions = []
    page_token = None

    try:
        service = build('classroom', 'v1', credentials=creds)
        while True:
            coursework = service.courses().courseWork()
            response = coursework.studentSubmissions().list(
                pageToken=page_token,
                courseId=course_id,
                courseWorkId=coursework_id,
                userId=user_id).execute()
            submissions.extend(response.get('studentSubmissions', []))
            page_token = response.get('nextPageToken', None)
            if not page_token:
                break

        if not submissions:
            print('No student submissions found.')

        print('Student Submissions:')
        for submission in submissions:
            print(f"Submitted at:"
                  f"{(submission.get('id'), submission.get('creationTime'))}")

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


if __name__ == '__main__':
    # Put the course_id, coursework_id and user_id of course whose list needs
    # to be submitted.
    classroom_list_student_submissions(453686957652, 466086979658, "me")

学生由用户的唯一 ID 或电子邮件地址（由 Google Admin SDK 返回）标识。当前用户还可以使用 "me" 简写形式来引用自己的 ID。

此外，您还可以针对课程中的所有作业获取学生提交的作业。为此，请使用文本 "-" 作为课程作业 ID，如以下示例所示：

Python

service.courses().courseWork().studentSubmissions().list(
    courseId=<course ID or alias>,
    courseWorkId='-',
    userId=<user ID>).execute()

如果您只对某些字段感兴趣，请考虑将请求限制在这些字段。这样可以显著加快处理您请求的速度。如需了解详情，请参阅使用部分资源。

所需范围取决于发出请求的用户在课程中的角色。如果用户是教师或网域管理员，请使用以下范围：

• https://www.googleapis.com/auth/classroom.coursework.students.readonly
• https://www.googleapis.com/auth/classroom.coursework.students

如果用户是学生，请使用以下范围：

• https://www.googleapis.com/auth/classroom.coursework.me.readonly
• https://www.googleapis.com/auth/classroom.coursework.me

拥有检索学生提交内容的权限并不意味着可以访问附件或附件元数据。实际上，这意味着，如果管理员不是课程成员，则可能不会看到附加的云端硬盘文件的标题。如果要允许管理员访问用户文件，请参阅全网域授权指南。

向学生的回复中添加附件

您可以通过附加 Link、DriveFile 或 YouTubeVideo 资源，将链接附加到学生提交的作业中。此过程通过 courses.courseWork.studentSubmissions.ModifyAttachments 来实现，如以下示例所示：

Python

classroom/snippets/classroom_add_attachment.py

在 GitHub 上查看

def classroom_add_attachment(course_id, coursework_id, submission_id):
    """
    Adds attachment to existing course with specific course_id.
    Load pre-authorized user credentials from the environment.
    TODO(developer) - See https://developers.google.com/identity
    for guides on implementing OAuth2 for the application.
    """
    creds, _ = google.auth.default()
    # pylint: disable=maybe-no-member
    request = {
        'addAttachments': [
            {'link': {'url': 'http://example.com/quiz-results'}},
            {'link': {'url': 'http://example.com/quiz-reading'}}
        ]
    }

    try:
        service = build('classroom', 'v1', credentials=creds)
        while True:
            coursework = service.courses().courseWork()
            coursework.studentSubmissions().modifyAttachments(
                courseId=course_id,
                courseWorkId=coursework_id,
                id=submission_id,
                body=request).execute()

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


if __name__ == '__main__':
    # Put the course_id, coursework_id and submission_id of course in which
    # attachment needs to be added.
    classroom_add_attachment('course_id', 'coursework_id', "me")

链接附件由目标网址定义；Google 课堂会自动获取标题和缩略图。如需了解其他资料的相应参考页面，

资料可以由课程教师或拥有相应学生提交的学生创建，但仅适用于其 courseWorkType 为 "ASSIGNMENT" 的学生提交的作业。

所需范围取决于发出请求的用户在课程中的角色。如果用户是教师，请使用以下范围：

• https://www.googleapis.com/auth/classroom.coursework.students

如果用户是学生，请使用以下范围：

• https://www.googleapis.com/auth/classroom.coursework.me

管理学生回复状态

学生的答案可以取消提交、上交或发回。StudentSubmission 中的状态字段指示当前状态。如需更改状态，请调用以下方法之一：

• courses.courseWork.studentSubmissions.turnIn
• courses.courseWork.studentSubmissions.return
• courses.courseWork.studentSubmissions.reclaim

所有这些方法都会采用空的正文。示例：

Python

service.courses().courseWork().studentSubmission().turnIn(
    courseId=<course ID or alias>,
    courseWorkId=<courseWork ID>,
    id=<studentSubmission ID>,
    body={}).execute()

只有拥有 StudentSubmission 的学生才能上交或收回此作业。只能收回已提交的作业。 课程教师只能返回已交状态的 StudentSubmission。

这不会更改 assignedGrade or draftGrade 的值。要向学生显示成绩，请参阅为学生的作业评分部分。

为学生的回答评分

StudentSubmission 资源有两个用于存储成绩的字段：assignedGrade（面向学生报告的成绩）和 draftGrade（暂不计算教师的成绩）。这些字段使用 courses.courseWork.studentSubmissions.patch 进行更新，其中字段掩码包含相应的字段，如以下示例所示。

Python

studentSubmission = {
  'assignedGrade': 99,
  'draftGrade': 80
}
service.courses().courseWork().studentSubmissions().patch(
    courseId=<course ID or alias>,
    courseWorkId=<courseWork ID>,
    id=<studentSubmission ID>,
    updateMask='assignedGrade,draftGrade',
    body=studentSubmission).execute()

使用“课堂”界面时，教师必须先保存草稿成绩，然后才能为其评分。然后将分配的成绩发回给学生。应用需要模拟此行为。您的应用可以通过以下两种方式之一为学生的作业评分：

• 仅分配 draftGrade。举例来说，这可以让教师在最终确定成绩之前手动查看成绩，这种做法非常有用。学生无法查看初始成绩。

• 同时分配 draftGrade 和 assignedGrade 以便对作业进行完全评分。

不要同时设置 draftGrade 也不要设置 assignedGrade。仅设置“assignGrade”可能会导致 Google 课堂界面出现异常行为。