Tạo và quản lý người giám hộ

Tài nguyên Guardian đạ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ề khoá học và bài tập của học sinh. 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ọ.

Lời mời được biểu thị bằng tài nguyên GuardianInvitation. Người dùng được mời 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 Google trước khi chấp nhận lời mời.

Khi người dùng được mời và trước khi họ chấp nhận lời mời, GuardianInvitation sẽ có trạng thái là PENDING. Sau khi người dùng chấp nhận lời mời, GuardianInvitation sẽ được đánh dấu là COMPLETED và một tài nguyên Guardian sẽ được tạo.

Trạng thái GuardianInvitation cũng có thể được thay đổi thành COMPLETED nếu trạng thá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 ứng dụng web Lớp học hoặc phương thức DeleteGuardian.

Ai 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 đượ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ộ:

  • https://www.googleapis.com/auth/classroom.guardianlinks.me.readonly: xem người giám hộ của chính người dùng.
  • https://www.googleapis.com/auth/classroom.guardianlinks.students.readonly: xem người giám hộ và lời mời dành cho người giám hộ cho học sinh mà người dùng dạy hoặc quản lý.
  • https://www.googleapis.com/auth/classroom.guardianlinks.students: xem và quản lý người giám hộ cũng như lời mời người giám hộ cho học sinh mà người dùng dạy hoặc quản lý.

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')))

Phản hồi 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(). Đây 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(). Theo mặc định, hệ thống sẽ chỉ trả về PENDING lời mời. Quản trị viên miề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ố states.

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')))

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

Để xác định người dùng nào là người giám hộ đang hoạt động của một học viên cụ thể, hãy 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.

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ý lời mời tham gia khoá học