Notificações push na API Classroom

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

Neste artigo, apresentamos uma visão geral conceitual, além de instruções simples sobre como começar a receber notificações push.

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

Com o recurso de notificações push da API Classroom, os aplicativos que usam essa API podem se inscrever para receber notificações quando dados forem alterados 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, é necessário configurar um tópico do Cloud Pub/Sub e fornecer o nome desse tópico ao criar um registro para o feed apropriado de notificações.

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 de terceiros 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 dele receberá notificações até que ele expire. Seu registro dura uma semana, mas você pode estendê-lo a qualquer momento antes que ele expire fazendo uma solicitação idêntica a registrations.create().

Seu tópico do Cloud Pub/Sub recebe apenas notificações sobre recursos que você pode ver com as credenciais fornecidas ao criar um registro. Por exemplo, se o usuário revogar a permissão do seu aplicativo ou for removido como professor, as notificações serão entregues por mais tempo.

Tipos de feed

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

  • Cada domínio tem um feed de alterações de listas de estudantes do domínio, que expõe notificações quando estudantes e professores entram e saem dos cursos no domínio.
  • Cada curso tem um feed de alterações de listas de estudantes, que expõe notificações quando estudantes e professores entram e saem dos cursos do curso.
  • Cada curso tem um feed de alterações nos trabalhos do curso, que expõe notificações quando qualquer trabalho do curso 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ê atende aos 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 para seu projeto do Play Console.

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

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

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

OBSERVAÇÃO: se você conceder permissão à conta de serviço de notificações push para publicar no seu tópico do Cloud Pub/Sub, os usuários que puderem fazer solicitações a partir do seu projeto do Play Console poderão determinar que ele existe e se registrar para receber notificações. Muitos aplicativos armazenam IDs do cliente OAuth no lado do cliente, assim os usuários finais podem fazer solicitações pelo seu projeto do Play Console. Se isso se aplica a você e você está preocupado com o envio de notificações indesejadas para o tópico do Cloud Pub/Sub ou com o conhecimento dos nomes dos tópicos do Cloud Pub/Sub usados para notificações push, registre-se para receber notificações push de outro projeto do Developer Console.

Registrar seu aplicativo para receber notificações

Quando você tiver um tema em que a conta de serviço de notificações push da API Classroom pode publicar, vai poder se inscrever para receber notificações usando o método registrations.create(). O método registrations.create() valida que 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 você não tiver concedido permissão de publicação para esse tópico.

Autorização

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 de notificações push (https://www.googleapis.com/auth/classroom.push-notifications) e os escopos necessários para visualizar os dados sobre quais notificações estão sendo enviadas.

  • Nos feeds de mudança de lista, 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 os feeds de alterações dos trabalhos do curso, isso significa as versões para "estudantes" do escopo de 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 enviadas, o aplicativo precisa reter uma concessão do 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 tentar se registrar para notificações usando apenas a autoridade delegada em todo o domínio, você 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 alterado. Para notificações sobre mudanças na lista de estudantes, é courses.students ou courses.teachers. Para mudanças no trabalho do curso, é courses.courseWork ou courses.courseWork.studentSubmissions.
  • Identificadores do recurso que foi 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 vão ser preenchidos e enviados sem modificações para courses.students.get() ou courses.teachers.get(). Da mesma forma, as mudanças na coleção courses.courseWork vão ter os campos courseId e id que podem ser enviados sem modificações a courses.courseWork.get() e as mudanças courseWorkIdos campos courseWorkIdcursos.cursos.fises courseIdsed.idcourses.courseWork.studentSubmissions.get()

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 as causou, que pode ser usado com registrations.delete() para cancelar o registro das notificações.