Quản lý người giám hộ

Tài nguyên người giám hộ đại diện cho người dùng, chẳng hạn như cha mẹ, là người nhận thông tin về các khoá học và bài tập của học viên. Người giám hộ (thường không phải là thành viên trong miền Lớp học của học viên) phải được mời bằng địa chỉ email của họ để trở thành người giám hộ.

Lời mời này sẽ tạo một tài nguyên Guardiancm với trạng thái PENDING. Sau đó, người dùng sẽ nhận được một email nhắc họ chấp nhận lời mời. Nếu địa chỉ email chưa liên kết với Tài khoản Google, người dùng sẽ được nhắc tạo một địa chỉ email trước khi chấp nhận lời mời.

Mặc dù lời mời có trạng thái là PENDING, nhưng người dùng có thể chấp nhận lời mời. Thao tác này sẽ tạo tài nguyên Người giám hộ và đánh dấu lời mời với trạng thái COMPLETED. Lời mời cũng có thể trở thành COMPLETED nếu lời mời hết hạn hoặc nếu người dùng được uỷ quyền huỷ lời mời (ví dụ: bằng phương thức PatchGuardianInvitation). Mối quan hệ Người giám hộ cũng có thể bị phá vỡ nếu người giám hộ, giáo viên trong Lớp học hoặc quản trị viên sử dụng giao diện người dùng Lớp học hoặc phương thức DeleteGuardian.

Những người có thể quản lý người giám hộ

Bảng sau đây mô tả các hành động có thể thực hiện liên quan đến người giám hộ, theo loại người dùng hiện được xác thực:

Bảng danh sách kiểm soát quyền truy cập (ACL) liên quan đến người giám hộ theo loại người dùng

Kính ngắm

Có 3 phạm vi cho phép bạn quản lý người giám hộ:

Tác vụ thông thường

Phần này mô tả một số thao tác phổ biến dành cho người giám hộ mà bạn nên thực hiện bằng API Google Lớp học.

Tạo lời mời cho người giám hộ

Ví dụ sau đây cho biết cách bạn có thể tạo lời mời cho người giám hộ bằng phương thức userProfiles.guardianInvitations.create():

Java

lớp học/snippets/src/main/java/CreateGuardian mộ.java
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': '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')))

Kết quả bao gồm một giá trị nhận dạng do máy chủ chỉ định. Bạn có thể dùng giá trị nhận dạng này để tham chiếu đến Guardiancm

Huỷ lời mời là người giám hộ

Để huỷ lời mời, hãy sửa đổi trạng thái của lời mời từ PENDING thành COMPLETE bằng cách gọi phương thức userProfiles.guardianInvitations.patch(). Xin lưu ý rằng đây hiện là cách duy nhất để xoá lời mời.

Java

lớp học/snippets/src/main/java/CancelGuardianGallery.java
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='student@mydomain.edu',
  invitationId=1234, # Replace with the invitation ID of the invitation you want to cancel
  updateMask='state',
  body=guardianInvitation).execute()

Liệt kê lời mời cho một học viên cụ thể

Bạn có thể xem danh sách tất cả lời mời đã gửi cho một học viên cụ thể bằng phương thức userProfiles.guardianInvitations.list():

Java

lớp học/snippets/src/main/java/ListGuardian ChecksBySV.java
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='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')))

Theo mặc định, chỉ PENDING lời mời sẽ được trả về. Là quản trị viên miền, bạn cũng có thể truy xuất lời mời ở trạng thái COMPLETED bằng cách cung cấp tham số trạng thái.

Liệt kê người giám hộ đang hoạt động

Nếu muốn xác định người dùng nào là người giám hộ đang hoạt động cho một học viên cụ thể, bạn có thể sử dụng phương thức userProfiles.guardians.list(). Người giám hộ đang hoạt động là người giám hộ đã chấp nhận lời mời qua email.

Java

lớp học/snippets/src/main/java/ListGuardians.java
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='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')))

Xoá người giám hộ

Bạn cũng có thể xoá người giám hộ khỏi học viên bằng cách sử dụng phương thức userProfiles.guardians.delete():

Java

lớp học/snippets/src/main/java/DeleteGuardian.java
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='student@mydomain.edu',
                                        guardianId='guardian@gmail.com').execute()