Créer et gérer des représentants légaux

Une ressource Guardian représente un utilisateur, tel qu'un parent, qui reçoit des informations sur les cours et les devoirs d'un élève. Le représentant légal, qui n'est généralement pas membre du domaine Classroom de l'élève, doit être invité à l'aide de son adresse e-mail.

Les invitations sont représentées par la ressource GuardianInvitation. L'utilisateur invité reçoit un e-mail lui demandant d'accepter l'invitation. Si l'adresse e-mail n'est pas associée à un compte Google, l'utilisateur est invité à en créer un avant d'accepter l'invitation.

Lorsque l'utilisateur est invité et avant qu'il n'accepte l'invitation, l'GuardianInvitation a l'état PENDING. Une fois que l'utilisateur a accepté l'invitation, le GuardianInvitation est marqué comme COMPLETED et une ressource Guardian est créée.

L'état GuardianInvitation peut également passer à COMPLETED s'il expire ou si un utilisateur autorisé annule l'invitation (par exemple, à l'aide de la méthode PatchGuardianInvitation). Un représentant légal, un enseignant Classroom ou un administrateur peuvent également rompre une relation de représentant légal à l'aide de l'application Web Classroom ou de la méthode DeleteGuardian.

Qui peut gérer les représentants légaux ?

Le tableau suivant décrit les actions qui peuvent être effectuées sur les représentants légaux, en fonction du type d'utilisateur authentifié :

Niveaux d'accès

Il existe trois niveaux d'accès qui vous permettent de gérer les représentants légaux :

• https://www.googleapis.com/auth/classroom.guardianlinks.me.readonly : afficher les représentants légaux d'un utilisateur.
• https://www.googleapis.com/auth/classroom.guardianlinks.students.readonly : affiche les représentants légaux et les invitations de représentants légaux pour les élèves dont l'utilisateur est l'enseignant ou l'administrateur.
• https://www.googleapis.com/auth/classroom.guardianlinks.students : permet d'afficher et de gérer les représentants légaux et les invitations de représentants légaux pour les élèves dont l'utilisateur est l'enseignant ou l'administrateur.

Actions courantes

Cette section décrit certaines des actions courantes que vous pouvez effectuer en tant que représentant légal à l'aide de l'API Google Classroom.

Créer une invitation pour un représentant légal

L'exemple suivant montre comment créer une invitation pour un représentant légal à l'aide de la méthode userProfiles.guardianInvitations.create() :

Java

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

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

La réponse inclut un identifiant attribué par le serveur qui peut être utilisé pour faire référence à GuardianInvitation.

Annuler une invitation envoyée à un représentant légal

Pour annuler une invitation, modifiez son état de PENDING à COMPLETE en appelant la méthode userProfiles.guardianInvitations.patch(). Il s'agit de la seule façon de supprimer une invitation.

Java

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

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

Lister les invitations pour un élève spécifique

Vous pouvez obtenir la liste de toutes les invitations envoyées à un élève spécifique à l'aide de la méthode userProfiles.guardianInvitations.list(). Par défaut, seules les invitations PENDING sont renvoyées. Un administrateur de domaine peut également récupérer les invitations à l'état COMPLETED en fournissant un paramètre states.

Java

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

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

Lister les représentants légaux actifs

Pour déterminer quels utilisateurs sont des représentants légaux actifs pour un élève spécifique, utilisez la méthode userProfiles.guardians.list(). Les représentants légaux actifs sont ceux qui ont accepté l'invitation.

Java

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

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

Remarque : Chaque réponse du représentant légal contient un UserProfile pour le représentant légal. Des champs d'application supplémentaires sont nécessaires pour afficher l'adresse e-mail et la photo de profil associées à ce profil. Seuls les administrateurs peuvent y accéder.

Supprimer des représentants légaux

Vous pouvez également supprimer un représentant légal d'un élève à l'aide de la méthode userProfiles.guardians.delete() :

Java

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

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