Gerenciar responsáveis

Um recurso de responsável representa um usuário, como um pai ou responsável, que recebe informações sobre os cursos e o trabalho de um estudante. O responsável, que normalmente não é membro do domínio do Google Sala de Aula do estudante, precisa ser convidado usando o endereço de e-mail dele para se tornar responsável.

Esse convite cria um recurso GuardianInvitation com um estado de PENDING. O usuário recebe um e-mail solicitando que aceite o convite. Se o endereço de e-mail não estiver associado a uma Conta do Google, o usuário vai precisar criar uma antes de aceitar o convite.

Enquanto o convite tem um estado de PENDING, o usuário pode aceitar o convite, que cria um recurso de guardião e marca o GuardianInvitation com um estado de COMPLETED. Um convite também pode se tornar COMPLETED se expirar ou se um usuário autorizado cancelar o convite (por exemplo, usando o método PatchGuardianInvitation). Uma relação de responsável também pode ser desfeita por um responsável, um professor do Google Sala de Aula ou um administrador usando a interface do usuário do Google Sala de Aula ou o método DeleteGuardian.

Quem pode gerenciar responsáveis

A tabela a seguir descreve as ações que podem ser realizadas em relação aos responsáveis, de acordo com o tipo de usuário autenticado no momento:

Escopos

Existem três escopos que permitem gerenciar os responsáveis:

• https://www.googleapis.com/auth/classroom.guardianlinks.me.readonly permite que você acesse os próprios responsáveis de um usuário.
• https://www.googleapis.com/auth/classroom.guardianlinks.students.readonly permite que você acesse os responsáveis e os GuardianInvitations dos estudantes que o usuário ensina ou administra.
• https://www.googleapis.com/auth/classroom.guardianlinks.students permite que você visualize e modifique os responsáveis e os convites de responsáveis para estudantes que o usuário leciona ou administra.

Ações comuns

Esta seção descreve algumas das ações comuns de responsáveis que você pode realizar usando a API Google Sala de Aula.

Criar um convite para o responsável

O exemplo a seguir mostra como criar um convite de responsável usando o método userProfiles.guardianInvitations.create():

Java

classroom/snippets/src/main/java/CreateGuardianInvitation.java

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

O resultado inclui um identificador atribuído pelo servidor que pode ser usado para se referir ao GuardianInvitation.

Cancelar um convite de responsável

Para cancelar um convite, modifique o estado dele de PENDING para COMPLETE chamando o método userProfiles.guardianInvitations.patch(). No momento, essa é a única maneira de remover um convite.

Java

classroom/snippets/src/main/java/CancelGuardianInvitation.java

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

Listar convites para um estudante específico

Você pode conferir uma lista de todos os convites enviados para um estudante específico usando o método userProfiles.guardianInvitations.list():

Java

classroom/snippets/src/main/java/ListGuardianInvitationsByStudent.java

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

Por padrão, apenas os convites PENDING são retornados. Como administrador do domínio, você também pode recuperar convites no estado COMPLETED fornecendo um parâmetro de estados.

Listar responsáveis ativos

Se você quiser determinar quais usuários são responsáveis legais ativos de um estudante específico, use o método userProfiles.guardians.list(). Os responsáveis ativos são aqueles que aceitaram o convite por e-mail.

Java

classroom/snippets/src/main/java/ListGuardians.java

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

Observação: cada resposta do responsável legal contém um UserProfile para o responsável. Os escopos extras são necessários para acessar o endereço de e-mail e a foto do perfil vinculados a esse perfil e só podem ser acessados por administradores.

Remover responsáveis

Também é possível remover um responsável de um estudante usando o método userProfiles.guardians.delete():

Java

classroom/snippets/src/main/java/DeleteGuardian.java

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