Cómo crear y administrar tutores

Un recurso Guardian representa a un usuario, como un padre, que recibe información sobre los cursos y el trabajo de curso de un estudiante. Se debe invitar al tutor, que por lo general no es miembro del dominio de Classroom del estudiante, con su dirección de correo electrónico.

Las invitaciones se representan con el GuardianInvitation recurso. El usuario invitado 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 solicitará al usuario que cree una antes de aceptar la invitación.

Cuando se invita al usuario y antes de que acepte la invitación, el GuardianInvitation tiene un estado PENDING. Una vez que el usuario acepta la invitación, el GuardianInvitation se marca como COMPLETED y se crea un Guardian recurso.

El estado de GuardianInvitation también se puede cambiar a COMPLETED si vence o si un usuario autorizado cancela la invitación (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 con la aplicación web 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 que se autentica:

Permisos

Existen tres permisos que te permiten administrar a los tutores:

• https://www.googleapis.com/auth/classroom.guardianlinks.me.readonly: Permite ver los tutores de un usuario.
• https://www.googleapis.com/auth/classroom.guardianlinks.students.readonly: Permite ver los tutores y las invitaciones de tutores de los estudiantes que el usuario enseña o administra.
• https://www.googleapis.com/auth/classroom.guardianlinks.students: Permite ver y administrar los tutores y las invitaciones de tutores de los estudiantes 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.

Cómo crear una invitación de tutor

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

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

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

Cómo cancelar una invitación de tutor

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

Puedes obtener una lista de todas las invitaciones que se enviaron para un estudiante específico con el userProfiles.guardianInvitations.list() método. De forma predeterminada, solo se mostrarán las invitaciones PENDING. Un administrador de dominio también puede recuperar invitaciones en el estado COMPLETED si proporciona un parámetro states.

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

Cómo enumerar los tutores activos

Para determinar qué usuarios son tutores activos de un estudiante específico, usa el userProfiles.guardians.list() método. Los tutores activos son aquellos que aceptaron la invitación.

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.

Quitar tutores

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

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