Seus usuários usam o Google Sala de Aula com o Google Meet? Confira o guia de início rápido do Apps Script que mostra como verificar a participação dos alunos nos cursos do Google Meet.

Notificações push na API Classroom

Você pode usar os métodos na coleção Registrations para receber notificações quando os dados forem alterados no Google Sala de Aula.

Este artigo apresenta uma visão geral conceitual com instruções simples sobre como começar a receber notificações push.

Visão geral das notificações push do Google Sala de Aula

O recurso de notificações push da API Classroom permite que os aplicativos que usam a API Classroom se inscrevam para receber notificações quando os dados mudam no Google Sala de Aula. As notificações são entregues a um tópico do Cloud Pub/Sub, geralmente alguns minutos após a alteração.

Para receber notificações push, é preciso configurar um tópico do Cloud Pub/Sub e fornecer o nome do tópico ao criar um registro para o feed de notificações apropriado.

Veja abaixo as definições dos principais conceitos usados nesta documentação:

  • Um destino é um lugar para onde as notificações são enviadas.
  • Um feed é um tipo de notificação em que um aplicativo terceirizado pode se inscrever. Por exemplo, "mudanças na lista de estudantes do curso 1234".
  • Um registro é uma instrução para a API Classroom enviar notificações de um feed específico para um destino.

Depois de criar um registro para um feed, o tópico do Cloud Pub/Sub desse registro receberá notificações desse feed até que ele expire. Seu registro dura uma semana, mas você pode estendê-lo a qualquer momento antes que expire. Para isso, faça uma solicitação idêntica ao registrations.create().

O tópico do Cloud Pub/Sub só recebe notificações sobre recursos que podem ser visualizados com as credenciais fornecidas ao criar um registro. Por exemplo, se o usuário revogar a permissão do aplicativo ou for removido como professor, as notificações vão ser mais entregues.

Tipos de feed

Atualmente, a API Classroom oferece três tipos de feed:

  • Cada domínio tem um feed de alterações na lista de domínios para o domínio, que expõe notificações quando estudantes e professores entram e saem dos cursos nesse domínio.
  • Cada curso tem um feed de alterações na lista de alunos, que mostra notificações quando estudantes e professores entram e saem dos cursos.
  • Cada curso tem um feed Mudanças nos trabalhos do curso, que expõe notificações quando qualquer trabalho ou objeto de envio de estudantes é criado ou modificado.

Como configurar um tópico do Cloud Pub/Sub

As notificações são entregues aos tópicos do Cloud Pub/Sub. No Cloud Pub/Sub, é possível receber notificações em um gancho da Web ou pesquisando um endpoint de assinatura.

Para configurar um tópico do Cloud Pub/Sub, faça o seguinte:

  1. Verifique se você cumpre os pré-requisitos do Cloud Pub/Sub.
  2. Configure um cliente do Cloud Pub/Sub.
  3. Revise os preços do Cloud Pub/Sub e ative o faturamento do seu projeto do Console do desenvolvedor.

  4. Crie um tópico do Cloud Pub/Sub no Console do desenvolvedor (mais fácil), usando a ferramenta de linha de comando (para uso programático simples) ou usando a API Cloud Pub/Sub. Observe que o Cloud Pub/Sub permite apenas um número limitado de temas. Portanto, usar um tópico para receber todas as suas notificações garante que você não terá problemas de escalonamento se o aplicativo se tornar popular.

  5. Crie uma assinatura no Cloud Pub/Sub para informar ao Cloud Pub/Sub como enviar suas notificações.

  6. Por fim, antes de se registrar para notificações push, é necessário conceder a permissão de conta de serviço (classroom-notifications@system.gserviceaccount.com) de notificações push para publicar no seu tópico.

OBSERVAÇÃO: se você conceder à conta de serviço de notificações push permissão para publicar seu tópico do Cloud Pub/Sub, os usuários que puderem fazer solicitações a partir do projeto do Console do desenvolvedor poderão determinar se ele existe e se registrar para receber notificações. Muitos aplicativos armazenam IDs do cliente OAuth no lado do cliente, para que os usuários finais possam fazer solicitações a partir do projeto do Console do desenvolvedor. Se isso se aplica a você e está preocupado com o fato de usuários finais enviarem notificações indesejadas para seu tópico do Cloud Pub/Sub ou de saber os nomes dos tópicos do Cloud Pub/Sub usados para notificações push, considere se inscrever para notificações push de um projeto diferente do Console do desenvolvedor.

Registrar o aplicativo para receber notificações

Depois que você tiver um tópico em que a conta de serviço das notificações push da API Classroom possa publicar, será possível se inscrever para receber notificações usando o método registrations.create(). O método registrations.create() valida se o tópico do Cloud Pub/Sub fornecido pode ser acessado pela conta de serviço de notificações push. O método falhará se a conta de serviço de notificações push não puder acessar o tópico. Por exemplo, se o tópico não existir ou se você não tiver concedido permissão de publicação nesse tópico.

Autorização

Assim como todas as chamadas para a API Classroom, as chamadas para registrations.create() precisam ser autorizadas com um token de autorização. Esse token de autenticação precisa incluir o escopo das notificações push (https://www.googleapis.com/auth/classroom.push-notifications) e os escopos necessários para ver os dados sobre quais notificações estão sendo enviadas.

  • Para feeds de alteração de lista de estudantes, isso significa o escopo das listas de estudantes ou, de preferência, a variante somente leitura (https://www.googleapis.com/auth/classroom.rosters.readonly ou https://www.googleapis.com/auth/classroom.rosters).
  • Para feeds de mudanças no trabalho do curso, isso significa as versões "alunos" do escopo do trabalho do curso ou, de preferência, a variante somente leitura (https://www.googleapis.com/auth/classroom.coursework.students.readonly ou https://www.googleapis.com/auth/classroom.coursework.students).

Para que as notificações sejam entregues, o aplicativo precisa reter uma concessão de acesso OAuth do usuário autorizado com os escopos necessários. Se o usuário desconectar o aplicativo, as notificações serão interrompidas. No momento, a delegação de autoridade em todo o domínio não é compatível com essa finalidade. Se você tentar fazer o registro para notificações usando apenas a autoridade delegada em todo o domínio, receberá um erro "@MissingGrant".

Como receber notificações

As notificações são codificadas com JSON e contêm:

  • O nome da coleção que contém o recurso que mudou. Para notificações sobre mudanças na lista de estudantes, acesse courses.students ou courses.teachers. Para mudanças no trabalho do curso, pode ser courses.courseWork ou courses.courseWork.studentSubmissions.
  • Identificadores do recurso alterado em um mapa. Esse mapa foi projetado para corresponder os argumentos ao método get do recurso apropriado. Para notificações sobre mudanças na lista de estudantes, os campos courseId e userId são preenchidos e podem ser enviados sem modificações para courses.students.get() ou courses.teachers.get(). Da mesma forma, as mudanças na coleção courses.courseWork terão os campos courseId e id que podem ser enviados sem modificações para courses.courseWork.get() e as mudanças para courses.course.id

O snippet de código a seguir demonstra um exemplo de notificação:

{
  "collection": "courses.students",
  "eventType": "CREATED",
  "resourceId": {
    "courseId": "12345",
    "userId": "45678"
  }
}

As notificações também têm um atributo de mensagem registrationId, contendo o identificador do registro que causou a notificação, que pode ser usado com registrations.delete() para cancelar o registro das notificações.