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ề 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ọ.

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 không liên kết với Tài khoản Google, người dùng sẽ được nhắc tạo một tài khoản 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 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ể thay đổi thành COMPLETED nếu 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). Người giám hộ, giáo viên Lớp học hoặc quản trị viên cũng có thể chấm dứt mối quan hệ 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.

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

Bảng sau đây mô tả những việc có thể làm đối với người giám hộ, tuỳ 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 cho người giám hộ của những học viên 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 cho người giám hộ đối với học viên 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ố hành động phổ biến của người giám hộ mà bạn có thể muốn thực hiện bằng Google Classroom API.

Tạo lời mời 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 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 này bao gồm một giá trị nhận dạng do máy chủ chỉ định mà bạn có thể dùng để tham chiếu đến GuardianInvitation.

Huỷ lời mời 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ể nhận được danh sách tất cả lời mời đã được gửi cho một học viên cụ thể bằng phương thức userProfiles.guardianInvitations.list(). Theo mặc định, chỉ có lời mời PENDING mới được trả về. 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 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ể, hãy 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
Tiếp
Tạo và quản lý nhóm học viên