The Classroom app supports three types of stream items: CourseWork
, CourseWorkMaterials
, and Announcements
. This guide
describes how to manage CourseWork
, but the APIs for all the stream items are
similar. See API resources
to learn more about the stream item types and their
differences.
The CourseWork
resource represents a work item that has been assigned to
students in a particular course, including any additional materials and details,
like due date or max score. There are four subtypes of CourseWork
: assignments, quiz assignments, short answer questions, and multiple-choice questions. The Classroom API supports
three of these subtypes: assignments, short answer questions, and
multiple-choice questions. These types are represented by the CourseWork.workType
field.
In addition to the CourseWork
resource, you can manage completed work
with the StudentSubmission
resource.
Create CourseWork
CourseWork
can only
be created on behalf of the course's teacher.
Attempting to create CourseWork
on behalf of a student, or a domain
administrator who is not a teacher in the course, results in a PERMISSION_DENIED
error. See User types
to learn more about the different
roles in Classroom.
When creating CourseWork
using the courses.courseWork.create
method, you
can attach links as materials
, shown in the sample code below:
Java
Python
The title
and workType
fields are required. All other fields are optional.
If state
is unspecified, the CourseWork
is created in a draft state.
Use a Link resource
with a specified target url
to include linked materials in the CourseWork
. Classroom
automatically fetches the title
and thumbnail image URL ( thumbnailUrl
). The
Classroom API also natively supports Google Drive and YouTube
materials, which can be included with a DriveFile
resource
or YouTubeVideo
resource
in a similar way.
To specify a due date, set the dueDate
and dueTime
fields to the
corresponding UTC time. The due date must be in the future.
The CourseWork
response includes a server-assigned identifier that can be used
to reference the assignment in other API requests.
Retrieve CourseWork
You can retrieve CourseWork
on behalf of students and teachers of the
corresponding course. You can also retrieve CourseWork
on behalf of domain
administrators, even if they aren't a teacher in the course. To retrieve a
specific CourseWork
, use courses.courseWork.get
. To retrieve all CourseWork
(optionally matching some criteria), use courses.courseWork.list
.
The required scope depends on the role that the requesting user has in the course. If the user is a student, use one of the following scopes:
-
https://www.googleapis.com/auth/classroom.coursework.me.readonly -
https://www.googleapis.com/auth/classroom.coursework.me
If the user is a teacher or a domain administrator, use one of the following scopes:
-
https://www.googleapis.com/auth/classroom.coursework.students.readonly -
https://www.googleapis.com/auth/classroom.coursework.students
Having permission to retrieve a CourseWork
does not imply
permissions to access materials or material metadata. In practice, this means
that an administrator may not see the title of an attached Drive
file if they're not a member of the course.
Manage student responses
A StudentSubmission
resource represents the work done by a student for a CourseWork
. The resource includes metadata related to the work, such
as the work status and grade. A StudentSubmission
is implicitly
created for each student when a new CourseWork
is created.
The following sections explain common actions that manage student responses.
Retrieve student responses
Students can retrieve their own submissions, teachers can retrieve submissions
for all students in their courses, and domain administrators can retrieve all
submissions for all students in their domain. Each StudentSubmission
is
assigned an identifier. If you know the identifier, use courses.courseWork.studentSubmissions.get
to retrieve the submission.
Use the courses.courseWork.studentSubmissions.list
method to get all StudentSubmission
resources that match some criteria, as shown in the
following sample:
Java
Python
Retrieve StudentSubmission
resources that belong to a particular student by
specifying the userId
parameter, as shown in the following sample:
Java
Python
Students are identified by the unique ID or email address, as represented in the Student
resource. The current user may also refer to their own ID using the "me"
shorthand.
It's also possible to retrieve student submissions for all assignments within a
course. To do so, use the literal "-"
as the courseWorkId
, as shown in the
following sample:
Java
service
.
courses
().
courseWork
().
studentSubmissions
()
.
list
(
courseId
,
"-"
)
.
set
(
"userId"
,
userId
)
.
execute
();
Python
service
.
courses
()
.
courseWork
()
.
studentSubmissions
()
.
list
(
courseId
=
< course
ID
or
alias
> ,
courseWorkId
=
'-'
,
userId
=
< user
ID
> )
.
execute
()
The required scope depends on the role that the requesting user has in the course. If the user is a teacher or a domain administrator, use the following scope:
-
https://www.googleapis.com/auth/classroom.coursework.students.readonly -
https://www.googleapis.com/auth/classroom.coursework.students
If the user is a student, use the following scope:
-
https://www.googleapis.com/auth/classroom.coursework.me.readonly -
https://www.googleapis.com/auth/classroom.coursework.me
Having permission to retrieve a StudentSubmission
does not imply permissions
to access attachments or attachment metadata. In practice, this means that an
administrator may not see the title of an attached Drive file if
they're not a member of the course.
Add attachments to a student response
You can attach links to a student submission by attaching a Link
, DriveFile
, or YouTubeVideo
resource. This is done with courses.courseWork.studentSubmissions.modifyAttachments
, as shown in the
following sample:
Java
Python
A Link
attachment is defined by the target url
; Classroom
automatically fetches the title
and thumbnail image ( thumbnailUrl
). See Material
to learn about materials that can be attached to StudentSubmissions
.
The StudentSubmission
can only be modified by a course teacher or by
the student that owns it. You can only attach Materials
if the CourseWorkType
of the StudentSubmission
is ASSIGNMENT
.
The required scope depends on the role that the requesting user has in the course. If the user is a teacher, use the following scope:
-
https://www.googleapis.com/auth/classroom.coursework.students
If the user is a student, use the following scope:
-
https://www.googleapis.com/auth/classroom.coursework.me
