Notificações push na API Classroom

É possível usar os métodos na Registrations coleção para receber notificações quando os dados mudam 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 Classroom se inscrevam para receber notificações quando os dados mudam no Google Sala de Aula. As notificações são entregues a um Cloud Pub/Sub tópico, geralmente alguns minutos após a mudança.

Para receber notificações push, você precisa configurar um tópico do Cloud Pub/Sub e fornecer 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ções que um aplicativo de terceiros pode assinar. Por exemplo, "mudanças na lista do curso 1234".
• Um registro é uma instrução para a API Classroom entregar 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é expirar. O registro dura uma semana, mas você pode estendê-lo a qualquer momento antes da expiração fazendo uma solicitação idêntica a 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 não serão mais entregues.

Tipos de feed

A API Classroom oferece três tipos de feed:

• Cada domínio tem um feed de mudanças na lista do domínio, que expõe notificações quando estudantes e professores entram e saem de cursos nesse domínio.
• Cada curso tem um feed de mudanças na lista do curso, que expõe notificações quando estudantes e professores entram e saem de cursos.
• Cada curso tem um feed de mudanças no trabalho do curso, que expõe notificações quando qualquer trabalho do curso ou objetos de envio do estudante são criados ou modificados nesse 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 do curso 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 para o feedType COURSE_ROSTER_CHANGES 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, 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:

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 console do desenvolvedor.

4. Crie um tópico do Cloud Pub/Sub no console do desenvolvedor (mais fácil), pela ferramenta de linha de comando (para uso programático simples) ou usando a API do 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 assinatura no Cloud Pub/Sub para informar ao Cloud Pub/Sub como entregar as notificações.

6. Por fim, antes de se inscrever para receber notificações push, você precisa conceder permissão à conta de serviço de notificações push ([e-mail]) para publicar no tópico.

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

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, você pode se inscrever para receber notificações usando o registrations.create() método. 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 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 a ele.

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 visualizar os dados sobre os quais as notificações estão sendo enviadas.

• Para feeds de mudança de lista, isso significa o escopo de listas ou (idealmente) a variante somente leitura (https://www.googleapis.com/auth/classroom.rosters.readonly ou https://www.googleapis.com/auth/classroom.rosters).
• Para feeds de mudança de trabalho do curso, isso significa as versões "estudantes" do escopo de trabalho do curso 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 permissão de acesso 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 com 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 que mudou. Para notificações sobre mudanças na lista, é 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 corresponder aos argumentos do método get do recurso apropriado. Para notificações sobre mudanças na lista, os campos courseId e userId serão preenchidos e poderão ser enviados sem modificação 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ção 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ção para courses.courseWork.studentSubmissions.get().

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

{
  "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, que pode ser usado com registrations.delete() para cancelar a inscrição de notificações.