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

Tài nguyên của người giám hộ đại diện cho một người dùng, chẳng hạn như cha mẹ, 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 của 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 tạo một tài nguyên GuardianInvitation có trạng thái là 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 tài khoản 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 một tài nguyên Guardian và đánh dấu GuardianInvitation bằng 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ụ: sử dụng phương thức PatchGuardianInvitation). Người giám hộ, giáo viên Lớp học hoặc quản trị viên cũng có thể huỷ mối quan hệ với người giám hộ bằng cách 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ả những hành động có thể thực hiện đối với người giám hộ, theo loại người dùng hiện đã được xác thực:

Bảng ACL liên quan đến người giám hộ theo loại người dùng

Phạm vi

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 mà người giám hộ có thể thực hiện bằng API Google Lớp học.

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

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

Java

classroom/snippets/src/main/java/CreateGuardianInvitation.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 có thể dùng để tham chiếu đến GuardianInvitation.

Huỷ lời mời dành cho 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

classroom/snippets/src/main/java/CancelGuardianInvitation.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ể lấy danh sách tất cả lời mời đã gửi cho một học viên cụ thể bằng cách sử dụng phương thức userProfiles.guardianInvitations.list():

Java

classroom/snippets/src/main/java/ListGuardianInvitationsByStudent.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, hệ thống chỉ trả về lời mời PENDING. 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 những người dùng là người giám hộ đang hoạt động của 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à những người giám hộ đã chấp nhận lời mời qua email.

Java

classroom/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 phương thức userProfiles.guardians.delete():

Java

classroom/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()
Trước
Tạo và quản lý giáo viên và học viên