Os professores que usam o Google Sala de Aula e ferramentas de terceiros enfrentam o desafio de configurar cursos e listas de alunos em várias plataformas. Isso pode ser feito manualmente, usando uploads de CSV ou inserindo e-mails um por um. No entanto, com a API Classroom, as ferramentas de terceiros podem reduzir a carga de trabalho dos professores ao se integrarem ao caso de uso mais comum da API: importação de turmas.
A importação de listas de estudantes permite que plataformas de terceiros extraiam os metadados, os professores e os estudantes de um curso por vez com permissões de professor ou administrador. Os professores podem extrair detalhes dos cursos que ensinam, enquanto os administradores têm acesso a detalhes de todos os cursos de um domínio. Essa flexibilidade permite que os desenvolvedores integrem as listas de alunos da Sala de Aula à plataforma de forma simples, seja no nível de professores individuais ou em todo o domínio, usando credenciais de administrador.
Antes de mergulhar nos detalhes técnicos de como uma integração de importação de lista de participantes pode ser feita, vamos analisar um exemplo de fluxo de trabalho:
No app de terceiros, o professor escolhe a opção para importar um curso do Google Sala de Aula.
O aplicativo de terceiros chama o método
courses.listpela API Classroom, que vai retornar uma resposta JSON com todos os cursos do professor.Com base na resposta JSON, o aplicativo de terceiros mostra os títulos dos cursos do professor para que ele selecione um. O aplicativo precisa acompanhar os IDs dos cursos para continuar para a próxima etapa.
Com o ID do curso selecionado, o aplicativo de terceiros chama os métodos
students.listeteachers.liste exibe todos os nomes no site para que os professores confirmem 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.
Para cada um dos métodos mencionados no fluxo de trabalho, você pode usar o API Explorer para saber exatamente como cada método se comporta. Também recomendamos a leitura dos seguintes textos antes de concluir este guia:
Primeiros passos
Antes de implementar os detalhes da importação da lista de participantes do Google Sala de Aula, você precisa determinar quais informações de curso e usuário serão necessárias para extrair pela API. É possível conferir quais metadados do curso estão disponíveis na documentação de referência, mas alguns campos obrigatórios ou comuns podem ser resumidos abaixo:
| Campo | Usar |
|---|---|
| id | Obrigatório para solicitações de API que recuperam estudantes ou professores |
| nome | Recomendado para facilitar o uso pelo usuário, ou seja, exibir no seu site |
| ownerId | Obrigatório ao importar em todo o domínio para identificar corretamente o professor principal de um curso |
Essas informações são recuperadas na etapa courses.list do fluxo de trabalho
acima. Nessa solicitação, é possível especificar alguns parâmetros. 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 vai retornar cursos dos seis estados de curso. Recomendamos especificar ACTIVE para recuperar os cursos que os professores estão usando no momento. |
| pageSize | Para professores que estão importando os 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, já que os administradores de domínio geralmente ministram cursos. Se não for especificado, a solicitação vai retornar cursos para professores em todo o domínio. |
| campos | Recomendamos diminuir o tempo de resposta da chamada de API. |
Usando os IDs de curso recuperados anteriormente, seu app agora pode recuperar a
lista de estudantes e professores auxiliares para esse curso ou cursos. Esse ID de 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 na documentação respectiva. Os dois campos mais usados e necessários estão no campo profile:
profile.name e profile.emailAddress.
| Campo | Usar |
|---|---|
| profile.name | Recomendado para facilitar o uso pelo usuário, ou seja, exibir no seu site |
| profile.emailAddress | Obrigatório para aplicativos que buscam identificar os estudantes de forma exclusiva |
Para extrair e usar qualquer um desses detalhes de curso ou turma do Google Sala de Aula, seu app precisa solicitar autorização dos usuários. Há três (3) escopos necessários para implementar esse fluxo de trabalho:
- https://www.googleapis.com/auth/classroom.courses.readonly
- Acesso somente leitura aos cursos do Google Sala de Aula
- https://www.googleapis.com/auth/classroom.rosters.readonly
- Acesso somente leitura às listas de chamada dos cursos do Google Sala de Aula (professores e estudantes)
- https://www.googleapis.com/auth/classroom.profile.emails
- Dá acesso de leitura à propriedade e-mail de professores e estudantes
Sincronizar as listas de funcionários com as notificações do Pub/Sub
À medida que o ano letivo avança, as listas podem mudar à medida que os estudantes abandonam ou adicionam cursos. Adicionar notificações do Pub/Sub permite que você mantenha seu aplicativo de terceiros sincronizado com as listas de chamada do Google Sala de Aula. Para receber notificações, configure um tópico do Google Cloud Pub/Sub e registre-o na API Classroom. Esse registro é uma solicitação para que o Google Sala de Aula envie dados do feed para o tópico. Esse feed será o acionador de eventos para a restauração da sincronização com a lista de participantes de um professor no Google Sala de Aula.
O uso de notificações push vai exigir um escopo extra, que não precisa ser enviado para verificação:
- https://www.googleapis.com/auth/classroom.push-notifications
- Permite que o app se registre para qualquer atividade de notificação push
Para mais detalhes sobre como fazer a integração com as notificações push do Google Sala de aula, consulte nosso guia de gerenciamento de notificações push.