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.

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

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

Para receber notificações push, configure um tópico do Cloud Pub/Sub e forneça o nome dele ao criar um registro para o feed de notificações adequado.

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

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

Seu tópico do Cloud Pub/Sub só recebe notificações sobre recursos que você pode visualizar 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 não serão mais enviadas.

Tipos de feed

A API Classroom oferece três tipos de feeds:

• Cada domínio tem um feed Mudanças na turma para o domínio, que mostra notificações quando estudantes e professores entram e saem dos cursos nesse domínio.
• Cada curso tem um feed de mudanças na lista de estudantes do curso, que mostra notificações quando estudantes e professores entram e saem dos cursos.
• Cada curso tem um feed Mudanças nas atividades do curso, que mostra notificações quando qualquer atividade ou envio de estudante é criado ou modificado no curso.

Observação: estamos cientes de um problema em que as notificações não são enviadas para mudanças em cursos em que o proprietário não faz parte de um domínio do Google Workspace for Education. Se você estiver trabalhando com cursos não vinculados a um domínio do Google Workspace for Education, lembre-se de que as notificações do COURSE_ROSTER_CHANGES feedType podem não funcionar.

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 webhook ou sondando 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. Analise os preços do Cloud Pub/Sub e ative o faturamento para seu projeto do Developer Console.

4. Crie um tópico do Cloud Pub/Sub no Developer Console (a maneira mais fácil), pela 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 terá problemas de escalonamento se o aplicativo se tornar popular.

5. Crie uma inscrição no Cloud Pub/Sub para informar ao Cloud Pub/Sub como entregar suas notificações.

6. Por fim, antes de se registrar para receber notificações push, é necessário conceder permissão à conta de serviço de notificações push ([e-mail]) para publicar no seu tópico.

Observação: se você conceder à conta de serviço de notificações push permissão para publicar no seu tópico do Cloud Pub/Sub, os usuários que puderem fazer solicitações do seu projeto do Developer Console poderão determinar que ele existe e se inscrever para receber notificações dele. Muitos aplicativos armazenam IDs de cliente OAuth no lado do cliente. Assim, os usuários finais podem fazer solicitações do projeto do Developer Console. Se isso se aplica a você e você se preocupa com o envio de notificações indesejadas para seu tópico do Cloud Pub/Sub ou com o conhecimento dos nomes dos tópicos do Cloud Pub/Sub que você usa para notificações push, considere registrar-se para receber notificações push de um projeto diferente do Developer Console.

Registrar seu aplicativo para receber notificações

Depois de ter um tópico em que a conta de serviço de notificações push da API Classroom pode publicar, registre-se para receber notificações usando o método registrations.create(). O método registrations.create() valida se a conta de serviço de notificações push pode acessar o tópico do Cloud Pub/Sub fornecido. O método falha se a conta de serviço de 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 permissão de publicação nele.

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

• Para feeds de mudança de lista, isso significa o escopo "Rosters" ou (idealmente) a variante somente leitura dele (https://www.googleapis.com/auth/classroom.rosters.readonly ou https://www.googleapis.com/auth/classroom.rosters).
• Para feeds de mudanças de atividades, isso significa as versões "estudantes" do escopo de atividades ou (idealmente) 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 manter uma concessão do OAuth do usuário autorizado com os escopos necessários. Se o usuário desconectar o aplicativo, as notificações vão parar. No momento, a delegação de autoridade em todo o domínio não é compatível para essa finalidade. Se você tentar se inscrever para receber notificações usando apenas a autoridade delegada em todo o domínio, vai receber um erro @MissingGrant.

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 escala, é 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 criado para corresponder aos argumentos ao método get do recurso apropriado. Para notificações sobre mudanças na lista de estudantes, 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 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, 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.