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

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

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

כששולחים למשתמש הזמנה, לפני שהוא מאשר אותה, הערך של GuardianInvitation הוא PENDING. אחרי שהמשתמש יאשר את ההזמנה, הערך של GuardianInvitation מסומן כ-COMPLETED ונוצר משאב Guardian.

המצב GuardianInvitation עשוי להשתנות ל-COMPLETED גם אם התוקף שלו פג או אם משתמש מורשה ביטל את ההזמנה (לדוגמה, באמצעות השיטה PatchGuardianInvitation). הורה או אפוטרופוס, מורה ב-Classroom או אדמין יכולים גם הם לבטל את הקשר עם התלמיד או התלמידה באמצעות אפליקציית האינטרנט של 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():

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

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

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

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

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

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

אפשר לקבל רשימה של כל ההזמנות שנשלחו לתלמידים ספציפיים באמצעות ה-method‏ userProfiles.guardianInvitations.list(). כברירת מחדל, רק PENDING הזמנות יחזרו. אדמין דומיין יכול גם לאחזר הזמנות בסטטוס COMPLETED על ידי ציון הפרמטר 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')))

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

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

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

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

אפשר גם להסיר הורה או אפוטרופוס מתלמיד/ה באמצעות השיטה 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()
הקודם
יצירה וניהול של הזמנות לקורסים