ایجاد و مدیریت نگهبان

یک منبع Guardian نمایانگر کاربری مانند والدین است که اطلاعاتی در مورد دوره‌ها و تکالیف دانش‌آموز دریافت می‌کند. ولی دانش‌آموز که معمولاً عضوی از دامنه Classroom او نیست، باید با استفاده از آدرس ایمیلش دعوت شود.

دعوت‌نامه‌ها توسط منبع GuardianInvitation نمایش داده می‌شوند. کاربر دعوت‌شده ایمیلی دریافت می‌کند که از او خواسته می‌شود دعوت را بپذیرد. اگر آدرس ایمیل با حساب گوگل مرتبط نباشد، از کاربر خواسته می‌شود قبل از پذیرش دعوت، یکی ایجاد کند.

وقتی کاربر دعوت می‌شود و قبل از اینکه دعوت را بپذیرد، GuardianInvitation در حالت PENDING قرار دارد. به محض اینکه کاربر دعوت را بپذیرد، GuardianInvitation به عنوان COMPLETED علامت‌گذاری می‌شود و یک منبع Guardian ایجاد می‌شود.

همچنین ممکن است وضعیت GuardianInvitation در صورت انقضا یا لغو دعوت توسط یک کاربر مجاز (مثلاً با استفاده از متد PatchGuardianInvitation ) به COMPLETED تغییر یابد. یک رابطه‌ی سرپرستی همچنین ممکن است توسط یک سرپرست، یک معلم کلاس درس یا یک مدیر، با استفاده از برنامه‌ی وب Classroom یا متد DeleteGuardian ، قطع شود.

چه کسی می‌تواند سرپرستان را مدیریت کند؟

جدول زیر اقداماتی را که می‌توان در رابطه با نگهبانان انجام داد، بسته به نوع کاربری که احراز هویت شده است، شرح می‌دهد:

جدول ACL های مربوط به نگهبان بر اساس نوع کاربر

محدوده‌ها

سه محدوده وجود دارد که به شما امکان مدیریت نگهبانان را می‌دهد:

  • 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 : مشاهده و مدیریت سرپرستان و دعوت‌نامه‌های سرپرست برای دانش‌آموزانی که کاربر به آنها آموزش می‌دهد یا آنها را مدیریت می‌کند.

اقدامات رایج

این بخش برخی از اقدامات رایج نگهبان را که ممکن است بخواهید با استفاده از API کلاس درس گوگل انجام دهید، شرح می‌دهد.

یک دعوتنامه سرپرست ایجاد کنید

مثال زیر نشان می‌دهد که چگونه می‌توانید با استفاده از متد userProfiles.guardianInvitations.create() یک دعوتنامه برای سرپرست ایجاد کنید:

جاوا

کلاس/قطعه کد/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;

پایتون 

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

پاسخ شامل یک شناسه اختصاص داده شده توسط سرور است که می‌تواند برای ارجاع به GuardianInvitation استفاده شود.

لغو دعوتنامه سرپرست

برای لغو دعوت، با فراخوانی متد userProfiles.guardianInvitations.patch() وضعیت دعوت را از PENDING به COMPLETE تغییر دهید. این تنها راه برای حذف دعوت است.

جاوا

کلاس/قطعه قطعه/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;

پایتون 

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

دعوت‌نامه‌های مربوط به یک دانشجوی خاص را فهرست کنید

شما می‌توانید با استفاده از متد userProfiles.guardianInvitations.list() لیستی از تمام دعوت‌نامه‌هایی که برای یک دانشجوی خاص ارسال شده است را دریافت کنید. به طور پیش‌فرض، فقط دعوت‌نامه‌های PENDING بازگردانده می‌شوند. مدیر دامنه همچنین می‌تواند با ارائه پارامتر states ، دعوت‌نامه‌هایی را که در حالت COMPLETED ، بازیابی کند.

جاوا

class/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;

پایتون 

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

فهرست سرپرستان فعال

برای تعیین اینکه کدام کاربران برای یک دانش‌آموز خاص، سرپرست فعال هستند، از متد userProfiles.guardians.list() استفاده کنید. سرپرستان فعال، سرپرستانی هستند که دعوت را پذیرفته‌اند.

جاوا

کلاس/قطعه کد/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;

پایتون 

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

سرپرستان را حذف کنید

همچنین می‌توانید با استفاده از متد userProfiles.guardians.delete() یک سرپرست (ولی) را از یک دانش‌آموز حذف کنید:

جاوا

class/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);
  }
}

پایتون 

service.userProfiles().guardians().delete(studentId='student@mydomain.edu',
                                        guardianId='guardian@gmail.com').execute()
قبلی
ایجاد و مدیریت دعوت نامه های دوره، ایجاد و مدیریت دعوت نامه های دوره
بعدی
ایجاد و مدیریت گروه های دانشجویی