Administrar tutores

Un recurso de tutor representa a un usuario, como un padre o una madre, que recibe información sobre los cursos y el trabajo de un estudiante. El tutor, que generalmente no es miembro del dominio de Classroom del estudiante, 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 la invitación tenga el estado PENDING, el usuario podrá aceptarla, lo que creará un recurso para tutores y marcará GuardianInvitation con el estado 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). Un tutor, un profesor de Classroom o un administrador también puede finalizar una relación con un tutor mediante 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 permisos que te permiten administrar a los tutores:

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

Acciones comunes

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

Crea una invitación para ser tutor

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

Java

classroom/snippets/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 la invitación a un tutor

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

Java

classroom/snippets/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()

Cómo ver la lista de invitaciones de un estudiante específico

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

Java

classroom/snippets/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 devolverán PENDING invitaciones. Como administrador del dominio, también puedes recuperar invitaciones en el estado COMPLETED si proporcionas un parámetro de estado.

Cómo ver la lista de tutores activos

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

Java

classroom/snippets/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 para el tutor. Se requieren permisos adicionales para ver la dirección de correo electrónico y la foto de perfil adjuntas a ese perfil, y solo los administradores pueden acceder a ellos.

Cómo quitar tutores

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

Java

classroom/snippets/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()