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

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

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

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

یک وضعیت GuardianInvitation نیز ممکن است به COMPLETED تغییر یابد، اگر منقضی شود یا یک کاربر مجاز دعوت را لغو کند (به عنوان مثال، با استفاده از روش PatchGuardianInvitation ). همچنین ممکن است یک قیم، معلم کلاس، یا مدیر، با استفاده از برنامه وب 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 : نگهبانان و دعوت نامه های سرپرست را برای دانش آموزانی که کاربر آموزش می دهد یا مدیریت می کند، مشاهده و مدیریت کنید.

اقدامات مشترک

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

یک دعوت نامه نگهبان ایجاد کنید

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

جاوا

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;

پایتون 

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 تغییر دهید. این تنها راه حذف دعوت نامه است.

جاوا

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;

پایتون 

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 برگردانده می‌شوند. یک مدیر دامنه همچنین می‌تواند دعوت‌نامه‌ها را در حالت COMPLETED با ارائه پارامتر states بازیابی کند.

جاوا

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;

پایتون 

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() استفاده کنید. قیم فعال قیمانی هستند که دعوت را پذیرفته اند.

جاوا

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;

پایتون 

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() یک سرپرست را از دانش آموز حذف کنید:

جاوا

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

پایتون 

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