Os complementos do Google Sala de Aula já estão disponíveis para desenvolvedores. Consulte a documentação sobre complementos para mais informações.

Esta página foi traduzida pela API Cloud Translation.

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.

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 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 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 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 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 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.