Erziehungsberechtigte verwalten

Eine Ressource für Erziehungsberechtigte steht für einen Nutzer, z. B. einen Elternteil, der Informationen zu den Kursen und Aufgaben eines Schülers erhält. Der Erziehungsberechtigte, der in der Regel kein Mitglied der Classroom-Domain des Schülers oder Studenten ist, muss über seine E-Mail-Adresse eingeladen werden, um Erziehungsberechtigter zu werden.

Mit dieser Einladung wird eine GuardianInvitation-Ressource mit dem Status PENDING erstellt. Der Nutzer erhält dann eine E-Mail, in der er aufgefordert wird, die Einladung anzunehmen. Wenn die E-Mail-Adresse nicht mit einem Google-Konto verknüpft ist, wird der Nutzer aufgefordert, ein Konto zu erstellen, bevor er die Einladung annehmen kann.

Solange die Einladung den Status PENDING hat, kann der Nutzer sie annehmen. Dadurch wird eine Erziehungsberechtigte-Ressource erstellt und die GuardianInvitation wird mit dem Status COMPLETED gekennzeichnet. Eine Einladung kann auch den Status COMPLETED erhalten, wenn sie abläuft oder ein autorisierter Nutzer sie storniert (z. B. mit der Methode PatchGuardianInvitation). Eine Erziehungsberechtigte-Beziehung kann auch von einem Erziehungsberechtigten, einer Classroom-Lehrkraft oder einem Administrator über die Classroom-Benutzeroberfläche oder die DeleteGuardian-Methode aufgehoben werden.

Wer darf Erziehungsberechtigte verwalten?

In der folgenden Tabelle werden die Aktionen beschrieben, die je nach Nutzertyp ausgeführt werden können:

Ebenen

Es gibt drei Bereiche, in denen Sie Erziehungsberechtigte verwalten können:

• Mit https://www.googleapis.com/auth/classroom.guardianlinks.me.readonly können Sie die eigenen Erziehungsberechtigten eines Nutzers aufrufen.
• Unter https://www.googleapis.com/auth/classroom.guardianlinks.students.readonly können Sie Erziehungsberechtigte und Erziehungsberechtigteinladungen für Schüler und Studenten aufrufen, die der Nutzer unterrichtet oder verwaltet.
• Mit https://www.googleapis.com/auth/classroom.guardianlinks.students können Sie Erziehungsberechtigte und Erziehungsberechtigteinladungen für Schüler und Studenten ansehen und ändern, die der Nutzer unterrichtet oder verwaltet.

Häufige Aktionen

In diesem Abschnitt werden einige der gängigen Aktionen von Erziehungsberechtigten beschrieben, die Sie mit der Google Classroom API ausführen können.

Einladung für Erziehungsberechtigten erstellen

Das folgende Beispiel zeigt, wie Sie mit der Methode userProfiles.guardianInvitations.create() eine Einladung für einen Erziehungsberechtigten erstellen:

Java

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

Auf GitHub ansehen

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

Das Ergebnis enthält eine vom Server zugewiesene Kennung, die sich auf die GuardianInvitation beziehen lässt.

Einladung eines Erziehungsberechtigten zurücknehmen

Wenn Sie eine Einladung stornieren möchten, ändern Sie den Status der Einladung von PENDING in COMPLETE, indem Sie die Methode userProfiles.guardianInvitations.patch() aufrufen. Das ist derzeit die einzige Möglichkeit, eine Einladung zu entfernen.

Java

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

Auf GitHub ansehen

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

Einladungen für einen bestimmten Schüler/Studenten auflisten

Mit der Methode userProfiles.guardianInvitations.list() können Sie eine Liste aller Einladungen abrufen, die an einen bestimmten Schüler oder Studenten gesendet wurden:

Java

classroom/snippets/src/main/java/ListGuardianInvitationsByStudent.java

Auf GitHub ansehen

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

Standardmäßig werden nur PENDING Einladungen zurückgegeben. Als Domainadministrator können Sie auch Einladungen im Status COMPLETED abrufen, indem Sie einen Parameter für den Status angeben.

Aktive Erziehungsberechtigte auflisten

Wenn Sie herausfinden möchten, welche Nutzer die Erziehungsberechtigten eines bestimmten Schülers sind, können Sie die Methode userProfiles.guardians.list() verwenden. Aktive Erziehungsberechtigte sind Erziehungsberechtigte, die die E-Mail-Einladung angenommen haben.

Java

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

Auf GitHub ansehen

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

Hinweis :Jede Antwort eines Erziehungsberechtigten enthält einen UserProfile für den Erziehungsberechtigten. Für die Anzeige der E-Mail-Adresse und des Profilbilds, die mit diesem Profil verknüpft sind, sind zusätzliche Berechtigungen erforderlich. Diese sind nur für Administratoren zugänglich.

Erziehungsberechtigte entfernen

Sie können einen Erziehungsberechtigten auch mit der Methode userProfiles.guardians.delete() von einem Schüler oder Studenten entfernen:

Java

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

Auf GitHub ansehen

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