ניהול של גרדיאנים

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

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

כשהסטטוס של ההזמנה הוא PENDING, המשתמש יכול לאשר אותה. הפעולה הזו יוצרת משאב של Guardian ומסמנת את GuardianInvitation בסטטוס 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 באמצעות קריאה ל-method‏ 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()

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

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

Java

classroom/snippets/src/main/java/ListGuardianInvitationsByStudent.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 על ידי ציון פרמטר states.

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

כדי לקבוע אילו משתמשים הם הורים או אפוטרופוסים פעילים של תלמיד או תלמידה מסוימים, אפשר להשתמש בשיטה 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()