A Guardian resource represents a user, such as a parent, who receives information about a student's courses and work. The guardian, who typically isn't a member of the student's Classroom domain, must be invited using their email address to become a guardian.
This invitation creates a
GuardianInvitation resource
with a state of PENDING. The user then receives an email prompting them to
accept the invitation. If the email address is not associated with a Google
account, the user is prompted to create one before accepting the invitation.
While the invitation has a state of PENDING, the user may accept the
invitation, which creates a Guardian resource and marks the GuardianInvitation
with a state of COMPLETED. An invitation may also become COMPLETED if it
expires, or if an authorized user cancels the invitation (for example, using the
PatchGuardianInvitation method). A Guardian relationship may also be broken by
a guardian, a Classroom teacher, or an administrator, using either the Classroom
user interface or the DeleteGuardian method.
Who can manage guardians
The following table describes the actions that can be performed with respect to guardians, according to the type of user currently authenticated:
Scopes
There are three scopes that allow you to manage guardians:
- https://www.googleapis.com/auth/classroom.guardianlinks.me.readonly allows you to view a user's own Guardians.
- https://www.googleapis.com/auth/classroom.guardianlinks.students.readonly allows you to view Guardians and GuardianInvitations for students that the user teaches or administers.
- https://www.googleapis.com/auth/classroom.guardianlinks.students allows you to view and modify Guardians and GuardianInvitations for students that the user teaches or administers.
Common actions
This section describes some of the common guardian actions that you may want to perform using the Google Classroom API.
Create a guardian invitation
The following example shows how you can create a guardian invitation using the
userProfiles.guardianInvitations.create() method:
Java
Python
guardianInvitation = {
'invitedEmailAddress': '[email protected]',
}
guardianInvitation = service.userProfiles().guardianInvitations().create(
studentId='[email protected]',
body=guardianInvitation).execute()
print("Invitation created with id: {0}".format(guardianInvitation.get('invitationId')))
The result includes a server-assigned identifier that can be used to refer to the GuardianInvitation.
Cancel a guardian invitation
To cancel an invitation, modify the state of the invitation from PENDING to
COMPLETE by calling the userProfiles.guardianInvitations.patch() method.
Note that this is currently the only way to remove an invitation.
Java
Python
guardian_invite = {
'state': 'COMPLETE'
}
guardianInvitation = service.userProfiles().guardianInvitations().patch(
studentId='[email protected]',
invitationId=1234, # Replace with the invitation ID of the invitation you want to cancel
updateMask='state',
body=guardianInvitation).execute()
List invitations for a specific student
You can get a list of all invitations that have been sent for a specific
student using the userProfiles.guardianInvitations.list() method:
Java
Python
guardian_invites = []
page_token = None
while True:
response = service.userProfiles().guardianInvitations().list(
studentId='[email protected]').execute()
guardian_invites.extend(response.get('guardian_invites', []))
page_token = response.get('nextPageToken', None)
if not page_token:
break
if not courses:
print('No guardians invited for this {0}.'.format(response.get('studentId')))
else:
print('Guardian Invite:')
for guardian in guardian_invites:
print('An invite was sent to '.format(guardian.get('id'),
guardian.get('guardianId')))
By default, only PENDING invitations will be returned. As a domain
administrator, you can also retrieve invitations in the COMPLETED state by
providing a states parameter.
List active guardians
If you wish to determine which users are active guardians for a specific
student, you can use the userProfiles.guardians.list() method. Active
guardians are guardians who have accepted the email invitation.
Java
Python
guardian_invites = []
page_token = None
while True:
response = service.userProfiles().guardians().list(studentId='[email protected]').execute()
guardian_invites.extend(response.get('guardian_invites', []))
page_token = response.get('nextPageToken', None)
if not page_token:
break
if not courses:
print('No guardians invited for this {0}.'.format(response.get('studentId')))
else:
print('Guardian Invite:')
for guardian in guardian_invites:
print('An invite was sent to '.format(guardian.get('id'),
guardian.get('guardianId')))
Remove guardians
You can also remove a guardian from a student, using the
userProfiles.guardians.delete() method:
Java
Python
service.userProfiles().guardians().delete(studentId='[email protected]',
guardianId='[email protected]').execute()