監護人資源代表的是接收學生課程和作業相關資訊的使用者 (例如父項)。監護人通常不是學生的 Classroom 網域成員，因此必須使用電子郵件地址接受邀請，才能成為監護人。
這項邀請會建立狀態為 PENDING 的 GuardianInvitation 資源。接著，使用者會收到電子郵件，提示他們接受邀請。如果電子郵件地址未連結至 Google 帳戶，系統會提示使用者先建立帳戶，再接受邀請。
邀請狀態為 PENDING 時，使用者可以接受邀請，系統會建立 Guardian 資源，並將 GuardianInvitation 標示為 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': '[email protected]',
}
guardianInvitation = service.userProfiles().guardianInvitations().create(
studentId='[email protected]',
body=guardianInvitation).execute()
print("Invitation created with id: {0}".format(guardianInvitation.get('invitationId')))
結果包含伺服器指派的 ID，可用來參照監護人邀請。
取消監護人邀請
如要取消邀請，請呼叫 userProfiles.guardianInvitations.patch() 方法，將邀請狀態從 PENDING 變更為 COMPLETE。請注意，目前這是移除邀請的唯一方式。
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()
可列出特定學生的邀請
您可以使用 userProfiles.guardianInvitations.list() 方法，取得已傳送給特定學生的所有邀請函清單：
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')))
根據預設，系統只會傳回 PENDING 份邀請。身為網域管理員，您也可以提供 states 參數，擷取 COMPLETED 狀態中的邀請。
列出有效監護人
如要判斷哪些使用者是特定學生的有效監護人，您可以使用 userProfiles.guardians.list() 方法。已接受電子郵件邀請的監護人即為「活躍監護人」。
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')))
移除監護人
您也可以使用 userProfiles.guardians.delete() 方法，從學生中移除監護人：
Java
Python
service.userProfiles().guardians().delete(studentId='[email protected]',
guardianId='[email protected]').execute()