É possível 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 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 entregues a um tópico do Cloud Pub/Sub, geralmente alguns 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 estudantes 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 recebe apenas notificações sobre recursos que você pode visualizar com as credenciais que você fornece 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.
- Cada curso tem um feed de mudanças nas atividades dos cursos, que expõe notificações quando qualquer trabalho do curso ou objetos de envio de estudantes são criados ou modificados no curso.
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, você pode 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:
- Atenda aos pré-requisitos do Cloud Pub/Sub.
- Configure um cliente do Cloud Pub/Sub.
- Consulte os preços do Cloud Pub/Sub e ative o faturamento no seu projeto do console do desenvolvedor.
Crie um tópico do Cloud Pub/Sub no Play Console (mais fácil), por meio da 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 dimensionamento se o aplicativo se tornar popular.
Crie uma assinatura no Cloud Pub/Sub para informar ao Pub/Sub como enviar suas notificações.
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 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 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 falhará 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 você não tiver concedido a ele permissão
de publicação sobre 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 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
ouhttps://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
ouhttps://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
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 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 escala, use
courses.students
oucourses.teachers
. Para mudanças no trabalho do curso, écourses.courseWork
oucourses.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 camposcourseId
euserId
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ãocourseId
eid
que podem ser enviados sem modificações para courses.courseWork.get() e as mudanças na coleção courses.courseWork.studentSubmissions terãocourseId
,courseWorkId
eid
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.