Notificações push na API Classroom

É possível usar os métodos na coleção Registrations para receber notificações quando os dados mudarem no Google Sala de Aula.

Este artigo oferece uma visão geral conceitual e 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 se inscrevam para receber notificações quando os dados mudarem no Google Sala de Aula. As notificações são enviadas para um tópico do Cloud Pub/Sub, geralmente em poucos minutos após a alteração.

Para receber notificações push, você precisa configurar um tópico do Cloud Pub/Sub e informar o nome dele ao criar um registro para o feed de notificações apropriado.

Confira 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 que um aplicativo de terceiros pode assinar. Por exemplo, "mudanças na lista de participantes do curso 1234".
  • Um registro é uma instrução para a API Classroom enviar notificações de um feed específico a um destino.

Depois de criar um registro para um feed, o tópico do Cloud Pub/Sub desse registro recebe notificações desse feed até que ele expire. Seu registro dura uma semana, mas você pode estender esse período a qualquer momento antes da expiração fazendo uma solicitação idêntica a registrations.create().

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

Tipos de feed

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

  • Cada domínio tem um feed de mudanças na lista de participantes do domínio, que exibe notificações quando estudantes e professores entram e saem de cursos nesse domínio.
  • Cada curso tem um feed de mudanças na lista de alunos, que mostra notificações quando estudantes e professores entram e saem de cursos nesse curso.
  • Cada curso tem um feed de mudanças de atividades do curso, que mostra notificações quando qualquer atividade do curso ou objetos de envio do estudante são criados ou modificados nesse curso.

Como configurar um tópico do Cloud Pub/Sub

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

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

  1. Cumpra os pré-requisitos do Cloud Pub/Sub.
  2. Configure um cliente do Cloud Pub/Sub.
  3. Consulte os preços do Pub/Sub do Cloud e ative o faturamento no seu projeto do console do desenvolvedor.

  4. Crie um tópico do Cloud Pub/Sub no Console do desenvolvedor (a maneira mais fácil), usando a ferramenta de linha de comando (para uso programático simples) ou 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 dimensionamento se o aplicativo se tornar popular.

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

  6. Por fim, antes de se registrar para as notificações push, você precisa 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 à conta de serviço das notificações por push permissão para publicar no seu tópico do Cloud Pub/Sub, os usuários que podem fazer solicitações do seu projeto do console do desenvolvedor poderão determinar se ele existe e se inscrever para receber notificações. Muitos aplicativos armazenam IDs de cliente OAuth no lado do cliente, portanto, os usuários finais podem fazer solicitações no seu projeto do Console do Desenvolvedor. Se isso se aplica a você e você está preocupado com usuários finais enviando notificações indesejadas para seu tópico do Cloud Pub/Sub ou conhecendo os nomes dos tópicos do Cloud Pub/Sub que você usa para notificações push, considere se inscrever para notificações push em um projeto diferente do console do desenvolvedor.

Registrar o app para receber notificações

Depois de ter um tópico que a conta de serviço de notificações por push da API Classroom pode publicar, você pode se registrar 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 falha se a conta de serviço das notificações push não conseguir acessar o tópico. Por exemplo, se o tópico não existir ou se você não tiver concedido a ele permissão de publicação.

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 todos os escopos necessários para acessar os dados sobre quais notificações estão sendo enviadas.

  • Para feeds de mudança de escala, isso significa o escopo de escalas 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 de trabalho do curso, isso significa as versões "dos estudantes" do escopo de trabalho do curso ou, de preferência, a variante de 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 app precisa reter uma concessão OAuth do usuário autorizado com os escopos necessários. Se o usuário desconectar o app, 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 se inscrever para notificações usando apenas a autoridade delegada em todo o domínio, vai 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, use courses.students ou courses.teachers. Para mudanças no trabalho do curso, é courses.courseWork ou courses.courseWork.studentSubmissions.
  • Identificadores do recurso que mudou, em um mapa. Esse mapa foi projetado para associar os argumentos ao método get do recurso apropriado. Para notificações sobre mudanças na lista de alunos, os campos courseId e userId serão preenchidos e poderão 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 campos courseId e id que podem ser enviados sem modificações para courses.courseWork.get() e as mudanças na coleção courses.courseWork.studentSubmissions terão campos courseId, courseWorkId e id que podem ser enviados sem modificações para courses.courseWork.studentSubmissions.get().

O snippet de código abaixo 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, que contém o identificador do registro que causou a notificação. Ele pode ser usado com registrations.delete() para cancelar o registro das notificações.