The Classroom UI supports five types of Classwork: Assignments,
Quiz Assignments, Short answer questions, Multiple-choice questions, and
Materials. The Classroom API currently supports three of these types, which
are known as CourseWorkType
for the API: Assignments, Short answer
questions, and Multiple-choice questions.
To access this functionality, you can use the CourseWork resource, which represents an Assignment or Question that has been assigned to students in a particular course, including any additional materials and details, like due date or max score.
In addition to the CourseWork resource, you can manage completed assignments
with the StudentSubmission
resource. The following sections describe these
in more detail.
Create assignments
Assignments can only be created on behalf of the course's teacher(s) and
attempting to create assignments in a course on behalf of a student will result
in a 403 PERMISSION_DENIED
error. Likewise, domain admins also cannot create
assignments for courses they do not teach and attempting to do so through the API
will also result in a 403 PERMISSION_DENIED
error.
When creating assignments using the courses.courseWork.create
method, you
can attach links as materials
, shown in the sample code below:
Java
Python
The result includes a server-assigned identifier that can be used to reference the assignment in other API requests.
To include linked materials in an assignment created via the Classroom API, use a Link resource, specifying the target URL. Classroom automatically fetches the title and thumbnail image. The Classroom API also natively supports Google Drive and YouTube materials, which can 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.
Retrieve assignments and questions
You can retrieve assignments and questions for students and teachers of the corresponding course or by a domain administrator. To retrieve a specific assignment or question, use courses.courseWork.get. To retrieve all assignments or questions (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 an assignment or question 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. If you want to allow administrators access to user files, see the domain-wide delegation guide.
Manage student responses
A StudentSubmission
resource represents the work done and grade of a student for an assignment or
question. A StudentSubmission
resource is implicitly created for each student when a new question or
assignment 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 student submission is
assigned an identifier; if you know the identifier, use
courses.courseWork.studentSubmissions.get
to retrieve it.
Use the courses.courseWork.studentSubmissions.list
method to get
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 of the user, as
returned by the Google Admin SDK. The current user may also refer to their own
ID using the "me"
shorthand.
It's also possible to get 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. Use the following scope if the user is a teacher or a domain administrator:
https://www.googleapis.com/auth/classroom.coursework.students.readonly
https://www.googleapis.com/auth/classroom.coursework.students
Use the following scope if the user is a student:
https://www.googleapis.com/auth/classroom.coursework.me.readonly
https://www.googleapis.com/auth/classroom.coursework.me
Having permission to retrieve a student submission 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. If you want to allow administrators access to user files, see the domain-wide delegation guide.
Adding 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 will automatically fetch the title and thumbnail image. You can learn about the other materials at their respective reference pages.
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 student submission is ASSIGNMENT
.
The required scope depends on the role that the requesting user has in the course. Use the following scope if the user is a teacher:
https://www.googleapis.com/auth/classroom.coursework.students
Use the following scope if the user is a student:
https://www.googleapis.com/auth/classroom.coursework.me
Manage student response state
A student response may be unsubmitted, turned in, or returned. The state field
in StudentSubmission
indicates the current state. To change the state, call
one of the following methods:
courses.courseWork.studentSubmissions.turnIn
courses.courseWork.studentSubmissions.return
courses.courseWork.studentSubmissions.reclaim
All of these methods take an empty body. Example:
Java
Python
service.courses().courseWork().studentSubmission().turnIn(
courseId=<course ID or alias>,
courseWorkId=<courseWork ID>,
id=<studentSubmission ID>,
body={}).execute()
Only the student that owns a StudentSubmission
may turn it in or reclaim it.
Only a turned in submission may be reclaimed. Course teachers can only return a
StudentSubmission
that is in the turned in state.
Grade student responses
The StudentSubmission
resource has two fields to store grades:
assignedGrade
, which is the grade reported to students, and draftGrade
,
which is a tentative grade visible only to teachers. These fields are updated
using courses.courseWork.studentSubmissions.patch
with a field mask
containing the appropriate fields, as shown in the following sample.
Java
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()
When working with the Classroom UI, teachers can't assign a grade until they have first saved a draft grade. The assigned grade can then be returned to a student. Applications need to emulate this behavior. Your application can grade a student's assignment in one of two ways:
Assign just the
draftGrade
. This is useful, for example, to let the teacher manually review grades before finalizing them. Students cannot see draft grades.Assign both the
draftGrade
andassignedGrade
to fully grade an assignment.
List assigned grades
You can list all grades for a particular coursework item by exploring the
courses.courseWork.studentSubmissions.list
method's response object:
Java
Python
response = coursework.studentSubmissions().list(
courseId=course_id,
courseWorkId=coursework_id,
pageSize=10).execute()
submissions.extend(response.get('studentSubmissions', []))
if not submissions:
print('No student submissions found.')
print('Student Submissions:')
for submission in submissions:
print(f"Submitted at:"
f"{(submission.get('userId'), submission.get('assignedGrade'))}")