Erziehungsberechtigte verwalten

Eine Ressource für Erziehungsberechtigte stellt einen Nutzer wie einen Elternteil dar, der Informationen über die Kurse und Arbeiten eines Schülers/Studenten erhält. Der Erziehungsberechtigte, der normalerweise kein Mitglied der Classroom-Domain des Schülers 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 wird dann per E-Mail aufgefordert, 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 annimmt.

Während die Einladung den Status PENDING hat, kann der Nutzer die Einladung annehmen. Dadurch wird eine Guardian-Ressource erstellt und Guardian Invitation mit dem Status COMPLETED markiert. Eine Einladung kann auch zu COMPLETED werden, wenn sie abläuft oder wenn ein autorisierter Nutzer die Einladung zurückzieht (z. B. mit der Methode PatchGuardianInvitation). Die Beziehung eines Erziehungsberechtigten kann auch von einem Erziehungsberechtigten, einer Classroom-Lehrkraft oder einem Administrator über die Classroom-Benutzeroberfläche oder die Methode DeleteGuardian aufgelöst werden.

Wer darf Erziehungsberechtigte verwalten?

In der folgenden Tabelle werden die Aktionen beschrieben, die für Erziehungsberechtigte ausgeführt werden können, je nach aktuell authentifiziertem Nutzertyp:

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.
• https://www.googleapis.com/auth/classroom.guardianlinks.students.readonly ermöglicht Ihnen, Guardians und Guardian Invitations für Schüler/Studenten aufzurufen, die der Nutzer unterrichtet oder verwaltet.
• Mit https://www.googleapis.com/auth/classroom.guardianlinks.students können Sie Guardians und Guardian Invitations für Schüler abrufen und bearbeiten, die vom Nutzer unterrichtet oder verwaltet werden.

Häufige Aktionen

In diesem Abschnitt werden einige gängige Aktionen für Erziehungsberechtigte beschrieben, die Sie mit der Google Classroom API ausführen können.

Einladung für Erziehungsberechtigte erstellen

Das folgende Beispiel zeigt, wie Sie mit der Methode userProfiles.guardianInvitations.create() eine Einladung für Erziehungsberechtigte erstellen können:

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, mit der auf die GuardianInvitation verwiesen werden kann.

Einladung eines Erziehungsberechtigten zurücknehmen

Wenn Sie eine Einladung zurücknehmen möchten, ändern Sie den Status der Einladung von PENDING in COMPLETE. Rufen Sie dazu die Methode userProfiles.guardianInvitations.patch() auf. Derzeit ist dies 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/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 mit dem Status COMPLETED abrufen, indem Sie einen Statusparameter angeben.

Aktive Erziehungsberechtigte auflisten

Mit der Methode userProfiles.guardians.list() können Sie ermitteln, welche Nutzer aktive Erziehungsberechtigte für einen bestimmten Schüler sind. 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 eine UserProfile für den Erziehungsberechtigten. Zusätzliche Bereiche sind erforderlich, um die E-Mail-Adresse und das Profilfoto aufzurufen, die an dieses Profil angehängt sind. Sie 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 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()