Administrar tutores

Un recurso de tutor representa a un usuario, como un padre, que recibe información sobre los cursos y el trabajo de un alumno. El tutor, que, por lo general, no es miembro del dominio de Classroom del alumno, debe recibir una invitación con su dirección de correo electrónico para convertirse en tutor.

Esta invitación crea un recurso GuardianInvitation con un estado de PENDING. Luego, el usuario recibe un correo electrónico en el que se le solicita que acepte la invitación. Si la dirección de correo electrónico no está asociada con una Cuenta de Google, se le pedirá al usuario que cree una antes de aceptar la invitación.

Mientras que la invitación tiene el estado PENDING, el usuario puede aceptar la invitación, lo que crea un recurso de Guardian y marca la GuardianInvitation con un estado de COMPLETED. Una invitación también puede convertirse en COMPLETED si vence o si un usuario autorizado la cancela (por ejemplo, con el método PatchGuardianInvitation). También se puede romper una relación con un tutor, de un profesor de Classroom o de un administrador por medio de la interfaz de usuario de Classroom o el método DeleteGuardian.

Quién puede administrar a los tutores

En la siguiente tabla, se describen las acciones que se pueden realizar con respecto a los tutores, según el tipo de usuario autenticado actualmente:

Permisos

Existen tres alcances que te permiten administrar a los tutores:

• https://www.googleapis.com/auth/classroom.guardianlinks.me.readonly te permite ver los propios tutores de un usuario.
• https://www.googleapis.com/auth/classroom.guardianlinks.students.readonly te permite ver los tutores y las invitaciones para los alumnos que el usuario enseña o administra.
• https://www.googleapis.com/auth/classroom.guardianlinks.students te permite ver y modificar Guardians y GuardianInvitations de los alumnos que el usuario enseña o administra.

Acciones comunes

En esta sección, se describen algunas de las acciones comunes de los tutores que puedes realizar con la API de Google Classroom.

Crea una invitación para tutores

En el siguiente ejemplo, se muestra cómo puedes crear una invitación para tutores mediante el método userProfiles.guardianInvitations.create():

Java

classroom/fragmentos/src/main/java/CreateGuardianInvitation.java

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

El resultado incluye un identificador asignado por el servidor que se puede usar para hacer referencia a GuardianInvitation.

Cómo cancelar una invitación para tutores

Para cancelar una invitación, modifica el estado de la invitación de PENDING a COMPLETE llamando al método userProfiles.guardianInvitations.patch(). Ten en cuenta que, por el momento, esta es la única manera de quitar una invitación.

Java

classroom/fragmentos/src/main/java/CancelGuardianInvitation.java

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

Enumerar las invitaciones de un alumno específico

Puedes obtener una lista de todas las invitaciones que se enviaron para un alumno específico con el método userProfiles.guardianInvitations.list():

Java

classroom/fragmentos/src/main/java/ListGuardianInvitationsByStudent.java

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

De forma predeterminada, solo se mostrarán las invitaciones de PENDING. Como administrador de dominio, también puedes recuperar invitaciones en el estado COMPLETED si proporcionas un parámetro de estados.

Enumerar tutores activos

Si quieres determinar qué usuarios son tutores activos de un alumno específico, puedes usar el método userProfiles.guardians.list(). Los tutores activos son tutores que aceptaron la invitación por correo electrónico.

Java

classroom/fragmentos/src/main/java/ListGuardians.java

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

Nota: Cada respuesta del tutor contiene un UserProfile. Se requieren permisos adicionales para ver la dirección de correo electrónico y la foto de perfil adjunta a ese perfil, y solo los administradores pueden acceder a ellos.

Quitar tutores

También puedes quitar a un tutor de un alumno mediante el método userProfiles.guardians.delete():

Java

classroom/fragmentos/src/main/java/DeleteGuardian.java

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