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 permite que plataformas de terceiros extraiam os metadados, os professores e os estudantes de um curso 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 mostra todos os nomes no site para que os professores confirmem na 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 documentos antes de concluir este guia:
Primeiros passos
Antes de implementar as especificidades 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. É 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 do curso 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 especificada, a API retornará cursos de todos os 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 porque os administradores de domínio geralmente ministram cursos. Se não for especificada, a solicitação retornará cursos para professores de 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 nas respectivas documentações. 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
- Fornece 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 de estudantes podem mudar conforme os alunos 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 requer 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 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.