Os professores que usam o Google Sala de Aula e ferramentas de terceiros precisam configurar cursos e listas em várias plataformas. Isso pode ser feito manualmente, seja usando uploads de CSV ou inserindo um e-mail de cada vez. Com a API Classroom, no entanto, ferramentas de terceiros podem reduzir as cargas de trabalho dos professores integrando-as ao caso de uso mais comum da API: a importação de listas de estudantes.
Com a importação de listas de estudantes, plataformas de terceiros recuperam os metadados, professores e estudantes de um curso com permissões de professor ou administrador. Os professores podem consultar os detalhes dos cursos que ensinam, enquanto os administradores têm acesso aos detalhes de todos os cursos em um domínio inteiro. Essa flexibilidade permite que os desenvolvedores integrem perfeitamente as listas de estudantes do Google Sala de Aula à plataforma, no nível de um professor individual ou em um domínio inteiro, usando credenciais de administrador.
Antes de mergulhar nos detalhes técnicos de como pode ser uma integração de importação de listas de alunos, primeiro vamos analisar um exemplo de fluxo de trabalho:
No aplicativo de terceiros, o professor escolhe a opção de importar um curso do Google Sala de Aula.
O aplicativo de terceiros chama o método
courses.listpela API Classroom, que retornará um JSON de resposta com todos os cursos do professor.Na resposta em JSON, o aplicativo de terceiros mostra os títulos dos cursos do professor para que ele selecione um. A inscrição precisará manter um registro dos IDs do curso para prosseguir para a próxima etapa.
Com o ID do curso selecionado, o app de terceiros chama os métodos
students.listeteachers.liste mostra todos os nomes no site para os professores confirmarem a importação.Usando os e-mails retornados nos JSONs de resposta
students.listeteachers.list, o aplicativo de terceiros convida os usuários a participar do curso recém-importado na plataforma deles.
Para cada um dos métodos mencionados no fluxo de trabalho, é possível usar o API Explorer para ver exatamente como cada método se comporta. Também recomendamos as seguintes pré-leituras antes de terminar este guia:
Vamos começar
Antes de implementar os detalhes da importação da lista de estudantes do Google Sala de Aula, você precisa determinar quais informações do curso e do usuário você precisará recuperar pela API. Confira os metadados do curso disponíveis na Documentação de referência, mas alguns campos obrigatórios ou comuns necessários podem ser resumidos abaixo:
| Campo | Usar |
|---|---|
| id | Obrigatório para solicitações de API que recuperam estudantes ou professores |
| name | Recomendado para facilitar o uso ao usuário, ou seja, exibir no seu site |
| ownerId | Obrigatório durante a importação em todo o domínio para identificar corretamente o professor principal de um curso |
As informações do curso são recuperadas na etapa courses.list do fluxo de trabalho
acima. Nessa solicitação, você pode especificar certos parâmetros de solicitação. Embora nenhum seja obrigatório para esse método, alguns parâmetros recomendados são:
| Parâmetro | Usar |
|---|---|
| courseState | Se não for especificado, a API retornará cursos de todos os seis estados de cursos. Recomendamos especificar ACTIVE para recuperar os cursos que os professores estão usando no momento. |
| pageSize | Para professores que estão importando seus próprios cursos, recomendamos especificar um pageSize pequeno (menos de 10) para diminuir o tempo de resposta da chamada de API. |
| pageToken | Obrigatório se você estiver usando solicitações paginadas. |
| teacherId | Recomendado porque os administradores de domínio costumam ministrar cursos. Se não for especificado, a solicitação retornará cursos para professores em todo o domínio. |
| campos | Recomendado para diminuir o tempo de resposta da chamada de API. |
Usando os IDs dos cursos recuperados anteriormente, seu aplicativo agora pode recuperar a lista de estudantes e professores auxiliares desse ou de cursos. Esse ID do curso é o único parâmetro de consulta obrigatório para teachers.list e students.list, mas também é recomendável especificar os parâmetros pageSize e fields para diminuir o tempo de resposta das chamadas de API.
Todos os campos disponíveis para os recursos de aluno e professor podem ser encontrados nas respectivas documentações. Os dois campos mais usados e normalmente obrigatórios estão em profile: profile.name e profile.emailAddress.
| Campo | Usar |
|---|---|
| profile.name | Recomendado para facilitar o uso ao usuário, ou seja, exibir no seu site |
| profile.emailAddress | Necessário para aplicativos que buscam identificar exclusivamente os estudantes |
Para recuperar e usar qualquer um desses detalhes do curso ou da lista de estudantes do Google Sala de Aula, seu aplicativo precisará solicitar uma autorização dos usuários. Existem três (3) escopos necessários para implementar esse fluxo de trabalho:
- https://www.googleapis.com/auth/classroom.courses.readonly
- Dá acesso somente leitura aos cursos do Google Sala de Aula.
- https://www.googleapis.com/auth/classroom.rosters.readonly
- Fornece acesso somente leitura às listas de cursos do Google Sala de Aula (professores e estudantes).
- https://www.googleapis.com/auth/classroom.profile.emails
- Concede acesso de leitura à propriedade email de professores e estudantes.
Sincronizar listas de estudantes com as notificações do Pub/Sub
À medida que o ano letivo avança, as listas podem mudar conforme os alunos abandonam ou adicionam cursos. Adicionar notificações do Pub/Sub permite manter seu aplicativo de terceiros sincronizado com as listas do Google Sala de Aula. Para receber notificações, configure um tópico do Google Cloud Pub/Sub e registre-o com a API Classroom. Esse registro é uma solicitação para o Google Sala de Aula enviar dados do feed especificado para o tema em questão. Esse feed será o acionador de eventos para sincronizar novamente com a lista de estudantes do Google Sala de Aula de um professor.
O uso de notificações push exige um escopo adicional, que não precisa ser enviado para verificação:
- https://www.googleapis.com/auth/classroom.push-notifications
- Permite que o app se registre em qualquer atividade de notificação push
Para mais detalhes sobre a integração com as notificações push do Google Sala de Aula, consulte nosso guia "Gerenciar notificações push".