Os professores que usam o Google Sala de Aula e ferramentas de terceiros enfrentam o desafio de configurar cursos e listas em várias plataformas. Isso pode ser feito manualmente, usando uploads de CSV ou inserindo e-mails um por um. No entanto, com a Classroom API, as ferramentas de terceiros podem reduzir a carga de trabalho dos professores ao fazer a integração com o caso de uso mais comum da API: importação de listas.
A importação de listas permite que plataformas de terceiros recuperem os metadados, professores e 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 de um domínio inteiro. Essa flexibilidade permite que os desenvolvedores integrem listas do Google Sala de Aula à plataforma deles de maneira simples, tanto no nível de um professor individual quanto em um domínio inteiro, usando credenciais de administrador.
Antes de analisar os detalhes técnicos de como uma integração de importação de listas pode ser, vamos revisar um exemplo de fluxo de trabalho:
No aplicativo de terceiros, um professor escolhe a opção de importar um curso do Google Sala de Aula .
O aplicativo de terceiros chama o método
courses.listpela Classroom API, 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 do curso 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 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 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, você precisa determinar quais informações de curso e usuário serão necessárias para 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 necessários 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 do usuário, ou seja, mostrar 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 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. 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 (menor que 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 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 do curso recuperados anteriormente, o aplicativo agora pode recuperar a lista de estudantes e professores auxiliares desse curso ou desses cursos. Esse ID do curso é o único parâmetro de consulta obrigatório para teachers.list e students.list, mas você também pode 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 estudantes
e professores
podem ser encontrados na documentação respectiva. Os dois campos mais usados com frequência e normalmente obrigatórios estão no campo profile:
profile.name e profile.emailAddress.
| Campo | Usar |
|---|---|
| profile.name | Recomendado para facilitar o uso do usuário, ou seja, mostrar no seu site |
| profile.emailAddress | Obrigatório para aplicativos que buscam identificar estudantes de maneira exclusiva |
Para recuperar e usar qualquer um desses detalhes de curso ou lista do Google Sala de Aula, seu aplicativo precisa solicitar autorização dos usuários. Há três (3) 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
- Fornece acesso somente leitura às listas de 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 à medida que os estudantes abandonam ou adicionam cursos. A adição de notificações do Pub/Sub permite manter o 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 na Classroom API. 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á os acionadores de eventos para a ressincronização com a lista 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 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 Gerenciar notificações push.