Como trabalhar com APIs de educação no Microsoft Graph
As APIs de educação no Microsoft Graph aprimoram os recursos e dados do Microsoft 365 com informações que são relevantes para cenários de educação, incluindo escolas, alunos, professores, aulas e matrículas. Isso facilita a criação de soluções que se integram aos recursos educacionais.
As APIs de educação incluem recursos de escalação e recursos de atribuições que podem ser usados para interação com os serviços de escalação no Microsoft Teams. Você pode usar esses recursos para gerenciar a lista de participantes de uma escola.
Autorização
Para chamar as APIs de educação no Microsoft Graph, o aplicativo precisará adquirir um token de acesso. Para obter detalhes sobre tokens de acesso, confira Obter tokens de acesso para chamar o Microsoft Graph. O aplicativo também precisará das permissões apropriadas. Para saber mais, confira Permissões de educação.
Permissões de aplicativo para permitir o consentimento dos administradores de TI da escola
Para implantar os aplicativos que são integrados às APIs de educação do Microsoft Graph, primeiramente, os administradores de TI da escola devem dar consentimento para as permissões solicitadas pelo aplicativo. Esse consentimento deve ser concedido apenas uma vez, a menos que as permissões mudem. Após o consentimento do administrador, o aplicativo está provisionado para todos os usuários no locatário.
Para mostrar uma caixa de diálogo de consentimento, use a chamada REST a seguir.
GET https://login.microsoftonline.com/{tenant}/adminconsent?
client_id={clientId}&state=12345&redirect_uri={redirectUrl}
| Parâmetro | Descrição |
|---|---|
| Tenant | ID do locatário da escola. Use a ID completa, que inclui onmicrosoft.com. |
| clientId | ID do cliente do aplicativo. |
| redirectUrl | URL de redirecionamento do aplicativo. |
Lista de participantes
As APIs de lista de participantes permitem extrair dados do locatário do Microsoft 365 de uma escola provisionado com o Microsoft School Data Sync. Essas APIs fornecem acesso às informações sobre escolas, seções, professores, alunos e listas de participantes. As APIs dão suporte a cenários somente aplicativo (sincronismo) e a cenários de aplicativo mais usuário (interativo). As APIs que dão suporte a cenários interativos aplicam políticas RBAC apropriadas da região, com base na função do usuário que está chamando a API. Isso fornece uma API consistente e uma superfície mínima de política, independentemente da configuração administrativa nos locatários. Além disso, as APIs também fornecem permissões específicas de educação, de modo a garantir que o usuário certo tenha acesso aos dados.
Você pode usar as APIs de escalação para permitir que um usuário do aplicativo saiba:
- Quem eu sou
- Quais aulas eu frequento ou ministro
- O que preciso fazer e quando
As APIs de escalação fornecem os seguintes recursos-chave:
- educationSchool – representa a escola.
- educationClass – representa uma aula em uma escola.
- educationTerm – representa uma parte designada do ano acadêmico.
- educationTeacher – representa um usuário com a função principal de ‘Professor’.
- educationStudent – representa um usuário com a função principal de 'aluno'.
As APIs de escalação dão suporte aos seguintes cenários:
- Listar todas as escolas
- Listar escolas nas quais uma aula é ministrada
- Listar escolas para um usuário
- Obter todas as aulas
- Obter aulas em um escola
- Listar aulas para um usuário
- Adicionar aulas a uma escola
- Obter alunos e professores para uma aula
- Adicionar membros a uma aula
- Listar professores para uma aula
- Obter usuários em uma escola
Atribuições
Você pode usar as APIs de educação relacionadas a atribuições para integrá-las às atribuições do Microsoft Teams. O Microsoft Teams no Microsoft 365 Educacional é baseado nas mesmas APIs educacionais e fornece um caso de uso para o que você pode fazer com as APIs. Seu aplicativo pode usar essas APIs para interagir com as tarefas em todo o ciclo de vida da tarefa.
As APIs de atribuição fornecem os seguintes recursos-chave:
- educationAssignment - O objeto principal da API de atribuições. As atribuições são tarefas ou unidades de trabalho atribuídas a um aluno ou membro da equipe em uma classe como parte do estudo.
- educationSubmission - Representa os recursos que um indivíduo (ou grupo) envia para uma tarefa, a nota associada e os comentários para essa tarefa.
- educationResource - Representa o objeto de aprendizagem que está sendo atribuído ou enviado. Um educationResource está associado a um educationAssignment e/ou um educationSubmission.
As APIs de atribuição suportam os seguintes cenários:
- Criar tarefa
- Publicar tarefa
- Criar recurso de tarefa
- Criar recurso de envio
- Enviar tarefa
- Cancelar o envio da tarefa
- Devolver notas e comentários ao aluno
- Obter os detalhes da tarefa
A seguir estão alguns casos de uso comuns para as APIs educacionais relacionadas a atribuições.
| Caso de uso | Descrição | Veja também |
|---|---|---|
| Criar tarefas | Um sistema externo pode criar uma tarefa para a classe e anexar recursos à tarefa. | Criar tarefa |
| Leia as informações da atribuição | Um aplicativo de análise pode obter informações sobre tarefas e envios dos alunos, incluindo datas e notas. | Obter a tarefa |
| Acompanhar os envios dos alunos | Seu aplicativo pode fornecer um painel do professor que mostra quantos envios de alunos precisam ser avaliados. | Recurso de submissão |
Próximas etapas
Use as APIs de educação do Microsoft Graph para criar soluções de educação que acessam listas de participantes da escola. Para saber mais:
- Explore os recursos e os métodos mais úteis para seu cenário.
- Experimente a API no Explorador do Graph.