ניהול אפוטרופוסים

משאב של אפוטרופוס מייצג משתמש, כמו הורה, שמקבל מידע על הקורסים ועל העבודה של התלמיד/ה. כדי להפוך לאפוטרופוסים, צריך להזמין את האפוטרופוס, שלרוב לא חבר בדומיין של התלמיד ב-Classroom, באמצעות כתובת האימייל שלו.

ההזמנה הזו יוצרת משאב GuardianInvitation עם מצב של PENDING. המשתמש יקבל אימייל עם בקשה לאשר את ההזמנה. אם כתובת האימייל לא משויכת לחשבון Google, המשתמש יתבקש ליצור כתובת כזו לפני אישור ההזמנה.

המצב של ההזמנה הוא PENDING, אבל המשתמש יכול לאשר את ההזמנה. פעולה זו יוצרת משאב מסוג Guardian ומסמנת את המצב של COMPLETED. הזמנה יכולה להפוך ל-COMPLETED אם היא פגה תוקף, או אם משתמש מורשה מבטל את ההזמנה (לדוגמה, באמצעות השיטה PatchGuardianInvitation). גם אפוטרופוס, מורה או אדמין ב-Classroom יכולים לבטל את הקשר בין אפוטרופוס, באמצעות ממשק המשתמש של Classroom או באמצעות השיטה DeleteGuardian.

מי יכול לנהל אפוטרופוסים

בטבלה הבאה מתוארות הפעולות שאפשר לבצע ביחס לאפוטרופוסים, לפי סוג המשתמש המאומת כרגע:

רמות

יש שלושה היקפים שבהם אפשר לנהל אפוטרופוסים:

• בכתובת 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():

Java

classroom/snippets/src/main/java/CreateGuardianInvitation.java

הצגת הקוד ב-GitHub

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': '[e-mail]',
}
guardianInvitation = service.userProfiles().guardianInvitations().create(
                      studentId='[e-mail]',
                          body=guardianInvitation).execute()
print("Invitation created with id: {0}".format(guardianInvitation.get('invitationId')))

התוצאה כוללת מזהה שהוקצה על ידי שרת, שאפשר להשתמש בו כדי להתייחס ל-GuardianInvitation.

ביטול הזמנה של אפוטרופוס

כדי לבטל הזמנה, צריך לשנות את המצב של ההזמנה מ-PENDING ל-COMPLETE. לשם כך, צריך לבצע קריאה לשיטה userProfiles.guardianInvitations.patch(). לידיעתכם, בשלב הזה זו הדרך היחידה להסיר הזמנה.

Java

classroom/snippets/src/main/java/CancelGuardianInvitation.java

הצגת הקוד ב-GitHub

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='[e-mail]',
  invitationId=1234, # Replace with the invitation ID of the invitation you want to cancel
  updateMask='state',
  body=guardianInvitation).execute()

הצגת רשימה של הזמנות לתלמיד/ה ספציפי/ת

כך אפשר לקבל רשימה של כל ההזמנות שנשלחו לתלמיד מסוים באמצעות השיטה userProfiles.guardianInvitations.list():

Java

classroom/snippets/src/main/java/ListGuardianInvitationsByתלמיד.java

הצגת הקוד ב-GitHub

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='[e-mail]').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')))

כברירת מחדל, יוחזרו רק PENDING הזמנות. אדמינים של דומיינים יכולים גם לאחזר הזמנות במצב COMPLETED על ידי ציון פרמטר מצבים.

הצגת רשימה של אפוטרופוסים פעילים

כדי לדעת אילו משתמשים מוגדרים כאפוטרופוסים פעילים של תלמיד מסוים, אפשר להשתמש בשיטה userProfiles.guardians.list(). אפוטרופוסים פעילים הם אפוטרופוסים שאישרו את ההזמנה באימייל.

Java

classroom/snippets/src/main/java/ListGuardians.java

הצגת הקוד ב-GitHub

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='[e-mail]').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')))

הערה: כל תגובה של אפוטרופוס כוללת UserProfile של האפוטרופוס. נדרשת היקפים נוספים כדי לראות את כתובת האימייל ואת תמונת הפרופיל שמצורפת לפרופיל, ורק אדמינים יכולים לגשת אליהם.

הסרת אפוטרופוסים

אפשר גם להסיר אפוטרופוסים של תלמידות ותלמידים באמצעות השיטה userProfiles.guardians.delete():

Java

classroom/snippets/src/main/java/DeleteGuardian.java

הצגת הקוד ב-GitHub

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='[e-mail]',
                                        guardianId='[e-mail]').execute()