管理监护人

Guardian 资源代表可以接收学生课程和作业相关信息的用户，例如家长。监护人（通常不是学生的 Google 课堂网域的成员）必须使用其电子邮件地址受邀成为监护人。

此邀请会创建一个状态为 PENDING 的 GuardianInvitation 资源。然后，用户会收到一封电子邮件，提示其接受邀请。如果该电子邮件地址未与 Google 帐号关联，系统会提示用户先创建一个 Google 帐号，然后再接受邀请。

虽然邀请的状态为 PENDING，但用户可以接受邀请，这会创建一个 Guardian 资源，并将 GuardianInvitation 标记为 COMPLETED 状态。如果邀请过期，或者如果获授权的用户取消了邀请（例如，使用 PatchGuardianInvitation 方法），则该邀请也可能会变为 COMPLETED。监护人、Google 课堂教师或管理员也可能会使用 Google 课堂界面或 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，您可以查看和修改用户讲授或管理的学生的监护人和监护人邀请。

常用操作

本部分将介绍您可能需要使用 GoogleClassroom API 执行的一些常见监护人操作。

创建监护人邀请

以下示例展示了如何使用 userProfiles.guardianInvitations.create() 方法创建监护人邀请：

Java

classroom/snippets/src/main/java/CreateGuardianInvitation.java

在 GitHub 上查看

GuardianInvitation guardianInvitation = null;

/* Create a GuardianInvitation object with state set to PENDING. See
https://developers.google.com/classroom/reference/rest/v1/userProfiles.guardianInvitations#guardianinvitationstate
for other possible states of guardian invitations. */
GuardianInvitation content =
    new GuardianInvitation()
        .setStudentId(studentId)
        .setInvitedEmailAddress(guardianEmail)
        .setState("PENDING");
try {
  guardianInvitation =
      service.userProfiles().guardianInvitations().create(studentId, content).execute();

  System.out.printf("Invitation created: %s\n", guardianInvitation.getInvitationId());
} catch (GoogleJsonResponseException e) {
  // TODO (developer) - handle error appropriately
  GoogleJsonError error = e.getDetails();
  if (error.getCode() == 404) {
    System.out.printf("There is no record of studentId: %s", studentId);
  } else {
    throw e;
  }
} catch (Exception e) {
  throw e;
}
return guardianInvitation;

Python

guardianInvitation = {
  'invitedEmailAddress': '[e-mail]',
}
guardianInvitation = service.userProfiles().guardianInvitations().create(
                      studentId='[e-mail]',
                          body=guardianInvitation).execute()
print("Invitation created with id: {0}".format(guardianInvitation.get('invitationId')))

结果将包含由服务器分配的标识符，该标识符可用于引用 GuardianInvitation。

取消监护人邀请

如需取消邀请，请调用 userProfiles.guardianInvitations.patch() 方法，将邀请状态从 PENDING 修改为 COMPLETE。请注意，这是目前移除邀请的唯一方式。

Java

classroom/snippets/src/main/java/CancelGuardianInvitation.java

在 GitHub 上查看

GuardianInvitation guardianInvitation = null;

try {
  /* Change the state of the GuardianInvitation from PENDING to COMPLETE. See
  https://developers.google.com/classroom/reference/rest/v1/userProfiles.guardianInvitations#guardianinvitationstate
  for other possible states of guardian invitations. */
  GuardianInvitation content =
      service.userProfiles().guardianInvitations().get(studentId, invitationId).execute();
  content.setState("COMPLETE");

  guardianInvitation =
      service
          .userProfiles()
          .guardianInvitations()
          .patch(studentId, invitationId, content)
          .set("updateMask", "state")
          .execute();

  System.out.printf(
      "Invitation (%s) state set to %s\n.",
      guardianInvitation.getInvitationId(), guardianInvitation.getState());
} catch (GoogleJsonResponseException e) {
  // TODO (developer) - handle error appropriately
  GoogleJsonError error = e.getDetails();
  if (error.getCode() == 404) {
    System.out.printf(
        "There is no record of studentId (%s) or invitationId (%s).", studentId, invitationId);
  } else {
    throw e;
  }
} catch (Exception e) {
  throw e;
}
return guardianInvitation;

Python

guardian_invite = {
     'state': 'COMPLETE'
}
guardianInvitation = service.userProfiles().guardianInvitations().patch(
  studentId='[e-mail]',
  invitationId=1234, # Replace with the invitation ID of the invitation you want to cancel
  updateMask='state',
  body=guardianInvitation).execute()

列出特定学生的邀请

您可以使用 userProfiles.guardianInvitations.list() 方法获取针对特定学生发送的所有邀请的列表：

Java

classroom/snippets/src/main/java/ListGuardianInvitationsByStudent.java

在 GitHub 上查看

List<GuardianInvitation> guardianInvitations = new ArrayList<>();
String pageToken = null;

try {
  do {
    ListGuardianInvitationsResponse response =
        service
            .userProfiles()
            .guardianInvitations()
            .list(studentId)
            .setPageToken(pageToken)
            .execute();

    /* Ensure that the response is not null before retrieving data from it to avoid errors. */
    if (response.getGuardianInvitations() != null) {
      guardianInvitations.addAll(response.getGuardianInvitations());
      pageToken = response.getNextPageToken();
    }
  } while (pageToken != null);

  if (guardianInvitations.isEmpty()) {
    System.out.println("No guardian invitations found.");
  } else {
    for (GuardianInvitation invitation : guardianInvitations) {
      System.out.printf("Guardian invitation id: %s\n", invitation.getInvitationId());
    }
  }
} catch (GoogleJsonResponseException e) {
  GoogleJsonError error = e.getDetails();
  if (error.getCode() == 404) {
    System.out.printf("There is no record of studentId (%s).", studentId);
  } else {
    throw e;
  }
} catch (Exception e) {
  throw e;
}
return guardianInvitations;

Python

guardian_invites = []
page_token = None

while True:
    response = service.userProfiles().guardianInvitations().list(
                                      studentId='[e-mail]').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 个邀请。作为网域管理员，您还可以通过提供 state 参数来检索处于 COMPLETED 状态的邀请。

列出活跃监护人

如果要确定哪些用户是特定学生的活跃监护人，您可以使用 userProfiles.guardians.list() 方法。活跃监护人是指已接受电子邮件邀请的监护人。

Java

classroom/snippets/src/main/java/ListGuardians.java

在 GitHub 上查看

List<Guardian> guardians = new ArrayList<>();
String pageToken = null;

try {
  do {
    ListGuardiansResponse response =
        service.userProfiles().guardians().list(studentId).setPageToken(pageToken).execute();

    /* Ensure that the response is not null before retrieving data from it to avoid errors. */
    if (response.getGuardians() != null) {
      guardians.addAll(response.getGuardians());
      pageToken = response.getNextPageToken();
    }
  } while (pageToken != null);

  if (guardians.isEmpty()) {
    System.out.println("No guardians found.");
  } else {
    for (Guardian guardian : guardians) {
      System.out.printf(
          "Guardian name: %s, guardian id: %s, guardian email: %s\n",
          guardian.getGuardianProfile().getName().getFullName(),
          guardian.getGuardianId(),
          guardian.getInvitedEmailAddress());
    }
  }

} catch (GoogleJsonResponseException e) {
  GoogleJsonError error = e.getDetails();
  if (error.getCode() == 404) {
    System.out.printf("There is no record of studentId (%s).", studentId);
  } else {
    throw e;
  }
} catch (Exception e) {
  throw e;
}
return guardians;

Python

guardian_invites = []
page_token = None

while True:
    response = service.userProfiles().guardians().list(studentId='[e-mail]').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')))

注意 ：每个监护人回复均包含针对监护人的 UserProfile。 需要额外的范围才能查看附加到该资料的电子邮件地址和个人资料照片，并且只有管理员才能访问。

移除监护人

您还可以使用 userProfiles.guardians.delete() 方法从学生中移除监护人：

Java

classroom/snippets/src/main/java/DeleteGuardian.java

在 GitHub 上查看

try {
  service.userProfiles().guardians().delete(studentId, guardianId).execute();
  System.out.printf("The guardian with id %s was deleted.\n", guardianId);
} catch (GoogleJsonResponseException e) {
  GoogleJsonError error = e.getDetails();
  if (error.getCode() == 404) {
    System.out.printf("There is no record of guardianId (%s).", guardianId);
  }
}

Python

service.userProfiles().guardians().delete(studentId='[e-mail]',
                                        guardianId='[e-mail]').execute()