Creare e gestire tutori

Una Guardianrisorsa rappresenta un utente, ad esempio un genitore, che riceve informazioni sui corsi e sui compiti di uno studente. Il tutore, che in genere non è membro del dominio Classroom dello studente, deve essere invitato utilizzando il suo indirizzo email.

Gli inviti sono rappresentati dalla risorsa GuardianInvitation. L'utente invitato riceve un'email che lo invita ad accettare l'invito. Se l'indirizzo email non è associato a un Account Google, all'utente viene chiesto di crearne uno prima di accettare l'invito.

Quando l'utente viene invitato e prima che accetti l'invito, lo stato di GuardianInvitation è PENDING. Una volta che l'utente accetta l'invito, GuardianInvitation viene contrassegnato come COMPLETED e viene creata una risorsa Guardian.

Lo stato GuardianInvitation potrebbe anche essere modificato in COMPLETED se scade o se un utente autorizzato annulla l'invito (ad esempio, utilizzando il metodo PatchGuardianInvitation). Un rapporto con un tutore può essere interrotto anche da un tutore, un insegnante di Classroom o un amministratore, utilizzando l'applicazione web Classroom o il metodo DeleteGuardian.

Chi può gestire i tutori

La seguente tabella descrive le azioni che possono essere eseguite in relazione ai tutori, a seconda del tipo di utente autenticato:

Tabella degli ACL relativi ai tutori per tipo di utente

Ambiti

Esistono tre ambiti che ti consentono di gestire i tutori:

  • https://www.googleapis.com/auth/classroom.guardianlinks.me.readonly: visualizza i tutori di un utente.
  • https://www.googleapis.com/auth/classroom.guardianlinks.students.readonly: visualizzare i tutori e gli inviti per gli studenti che l'utente gestisce o a cui insegna.
  • https://www.googleapis.com/auth/classroom.guardianlinks.students: visualizzare e gestire i tutori e gli inviti per gli studenti che l'utente gestisce o a cui insegna.

Azioni comuni

Questa sezione descrive alcune delle azioni comuni dei tutori che potresti voler eseguire utilizzando l'API Google Classroom.

Creare un invito per un tutore

L'esempio seguente mostra come creare un invito per un tutore utilizzando il metodo 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': '[email protected]',
}
guardianInvitation = service.userProfiles().guardianInvitations().create(
                      studentId='[email protected]',
                          body=guardianInvitation).execute()
print("Invitation created with id: {0}".format(guardianInvitation.get('invitationId')))

La risposta include un identificatore assegnato dal server che può essere utilizzato per fare riferimento a GuardianInvitation.

Annullare un invito per un tutore

Per annullare un invito, modifica lo stato dell'invito da PENDING a COMPLETE chiamando il metodo userProfiles.guardianInvitations.patch(). Questo è l'unico modo per rimuovere un invito.

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='[email protected]',
  invitationId=1234, # Replace with the invitation ID of the invitation you want to cancel
  updateMask='state',
  body=guardianInvitation).execute()

Elencare gli inviti per uno studente specifico

Puoi ottenere un elenco di tutti gli inviti inviati per uno studente specifico utilizzando il metodo userProfiles.guardianInvitations.list(). Per impostazione predefinita, verranno restituiti solo PENDING inviti. Un amministratore di dominio può anche recuperare gli inviti nello stato COMPLETED fornendo un parametro 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='[email protected]').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')))

Elenca i tutori attivi

Per determinare quali utenti sono tutori attivi di uno studente specifico, utilizza il metodo userProfiles.guardians.list(). I tutori attivi sono quelli che hanno accettato l'invito.

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='[email protected]').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')))

Rimuovere i tutori

Puoi anche rimuovere un tutore da uno studente utilizzando il metodo 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='[email protected]',
                                        guardianId='[email protected]').execute()
Indietro
Creare e gestire gli inviti ai corsi
Avanti
Creare e gestire gruppi di studenti