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.
Com a importação de listas, as plataformas de terceiros podem recuperar os metadados, os professores e os estudantes de um curso, um por um, com permissões de professor ou administrador. Os professores podem recuperar detalhes dos cursos que ensinam, enquanto os administradores têm acesso a detalhes de todos os cursos em um domínio inteiro. Essa flexibilidade permite que os desenvolvedores integrem as turmas do Google Sala de Aula à plataforma deles, tanto no nível de um professor quanto em todo um domínio, usando credenciais de administrador.
Antes de entrar nos detalhes técnicos de como uma integração de importação de lista pode ser, 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 retorna um JSON de resposta com todos os cursos do professor.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 na 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 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, use o API Explorer para ver exatamente como cada método se comporta. Também recomendamos as seguintes leituras prévias antes de terminar este guia:
Primeiros passos
Antes de implementar os detalhes da importação de listas do Google Sala de Aula, determine quais informações de curso e usuário você precisa recuperar pela API. Você pode conferir quais metadados do curso estão disponíveis na documentação de referência, mas alguns campos obrigatórios ou comuns necessários podem ser resumidos abaixo:
| Campo | Usar |
|---|---|
| ID | Necessário para solicitações de API que recuperam estudantes ou professores |
| nome | Recomendado para facilitar o uso pelo usuário, ou seja, exibição 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 determinados 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 de todos os seis estados do 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 costumam ministrar cursos. Se não for especificado, a solicitação vai retornar cursos para professores em todo o domínio. |
| campos | Recomendado para diminuir o tempo de resposta da chamada de API. |
Usando os IDs de curso recuperados anteriormente, seu aplicativo agora pode recuperar a
lista de estudantes e professores auxiliares desse curso ou desses cursos. Esse ID é o único parâmetro de consulta obrigatório para teachers.list e students.list, mas talvez você queira 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 estudante e professor podem ser encontrados na documentação respectiva. Os dois campos mais usados e normalmente obrigató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, exibição no seu site |
| profile.emailAddress | Obrigatório para aplicativos que buscam identificar estudantes de forma exclusiva. |
Para recuperar e usar qualquer um desses detalhes do curso ou da lista do Google Sala de Aula, seu aplicativo precisa solicitar autorização dos usuários. Há três escopos obrigatórios para implementar esse fluxo de trabalho:
- https://www.googleapis.com/auth/classroom.courses.readonly
- Fornece acesso somente leitura aos cursos do Google Sala de Aula.
- https://www.googleapis.com/auth/classroom.rosters.readonly
- Concede acesso somente leitura às listas de estudantes 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 listas com notificações do Pub/Sub
À medida que o ano letivo avança, as listas podem mudar conforme os estudantes desistem ou adicionam cursos. Ao adicionar notificações do Pub/Sub, você mantém seu aplicativo de terceiros sincronizado com as turmas 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 especificado para o tópico especificado. Esse feed será o gatilho de evento para uma nova sincronização com a lista de uma turma do Google Sala de Aula.
Para usar notificações push, é necessário 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 integrar com as notificações push do Google Sala de Aula, consulte nosso guia de gerenciamento de notificações push.