監護人資源代表接收學生課程和作業相關資訊的使用者 (例如父項)。監護人 (通常不是學生的 Classroom 網域成員) 需要使用他們的電子郵件地址受邀擔任監護人。
這個邀請會建立狀態為 PENDING 的 GuardianInvite 資源。然後使用者會收到提示他們接受邀請的電子郵件。如果電子郵件地址未連結至 Google 帳戶，系統會在接受邀請之前提示使用者建立帳戶。
雖然邀請狀態為 PENDING，但使用者可能會接受邀請，藉此建立 Guardian 資源並將 Guardian 邀請標示為 COMPLETED 狀態。如果邀請過期或有授權使用者取消邀請 (例如使用 PatchGuardianInvitation 方法)，邀請也可能變成 COMPLETED。監護人、Classroom 老師或管理員 (使用 Classroom 使用者介面或 DeleteGuardian 方法) 也可能破壞監護人關係。
誰可以管理監護人
下表根據目前驗證的使用者類型，說明您可對監護人執行的動作：
範圍
您可透過以下三種範圍管理監護人：
- https://www.googleapis.com/auth/classroom.guardianlinks.me.readonly 可讓您查看使用者自己的監護人。
- https://www.googleapis.com/auth/classroom.guardianlinks.students.readonly 可讓您查看使用者授課或管理的學生的監護人和監護人邀請。
- https://www.googleapis.com/auth/classroom.guardianlinks.students 可讓您查看及修改使用者所授課或管理的監護人和監護人邀請。
常用操作
本節說明您可能想使用 Google Classroom API 執行的常見監護人動作。
建立監護人邀請
以下範例說明如何使用 userProfiles.guardianInvitations.create() 方法建立監護人邀請：
Java
Python
guardianInvitation = {
'invitedEmailAddress': 'guardian@gmail.com',
}
guardianInvitation = service.userProfiles().guardianInvitations().create(
studentId='student@mydomain.edu',
body=guardianInvitation).execute()
print("Invitation created with id: {0}".format(guardianInvitation.get('invitationId')))
結果包含伺服器指派 ID，可用來參照 GuardianInvite。
取消監護人邀請
如要取消邀請，請呼叫 userProfiles.guardianInvitations.patch() 方法，將邀請狀態從 PENDING 修改為 COMPLETE。請注意，目前這是移除邀請的唯一方式。
Java
Python
guardian_invite = {
'state': 'COMPLETE'
}
guardianInvitation = service.userProfiles().guardianInvitations().patch(
studentId='student@mydomain.edu',
invitationId=1234, # Replace with the invitation ID of the invitation you want to cancel
updateMask='state',
body=guardianInvitation).execute()
列出特定學生的邀請
您可以使用 userProfiles.guardianInvitations.list() 方法，取得已針對特定學生傳送的所有邀請清單：
Java
Python
guardian_invites = []
page_token = None
while True:
response = service.userProfiles().guardianInvitations().list(
studentId='student@mydomain.edu').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')))
根據預設，系統只會傳回 PENDING 份邀請。網域管理員也可以提供狀態參數來擷取 COMPLETED 狀態的邀請。
列出有效的監護人
如要判斷哪些使用者是特定學生的有效監護人，可以使用 userProfiles.guardians.list() 方法。「活躍的監護人」是指已接受電子郵件邀請的監護人。
Java
Python
guardian_invites = []
page_token = None
while True:
response = service.userProfiles().guardians().list(studentId='student@mydomain.edu').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')))
移除監護人
您也可以使用 userProfiles.guardians.delete() 方法移除學生的監護人：
Java
Python
service.userProfiles().guardians().delete(studentId='student@mydomain.edu',
guardianId='guardian@gmail.com').execute()