Administrar tutores

Un recurso Guardian representa a un usuario, como un padre, que recibe información sobre los cursos y el trabajo de un alumno. Se debe invitar al tutor que no suele ser miembro del dominio de Classroom del alumno mediante su dirección de correo electrónico para que se convierta en tutor.

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

Si bien la invitación tiene el estado PENDING, el usuario puede aceptarla, lo que crea un recurso Guardian y marca 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 pueden romper una relación de 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 las invitaciones a tutores y tutores para los alumnos que el usuario enseña o administra.
• https://www.googleapis.com/auth/classroom.guardianlinks.students te permite ver y modificar las invitaciones a tutores y tutores para 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 llevar a cabo con la API de Google Classroom.

Crea una invitación para ser tutor

En el siguiente ejemplo, se muestra cómo crear una invitación para tutores 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 la GuardianInvitation.

Cómo cancelar una invitación a un tutor

Para cancelar una invitación, modifica su estado de PENDING a COMPLETE llamando al método userProfiles.guardianInvitations.patch(). 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()

Enumerar las invitaciones a 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/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 mostrarán PENDING invitaciones. Como administrador de dominio, también puedes recuperar invitaciones en estado COMPLETED si proporcionas un parámetro de estados.

Enumerar los tutores activos

Si deseas determinar qué usuarios son tutores activos para un alumno específico, puedes usar el método userProfiles.guardians.list(). Los tutores activos son los 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 este. 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.

Quitar tutores

También puedes quitar a un tutor de un alumno mediante 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()