Como trabalhar com APIs de educação no Microsoft Graph

Importante

As APIs na versão /beta no Microsoft Graph estão sujeitas a alterações. Não há suporte para o uso dessas APIs em aplicativos de produção. Para determinar se uma API está disponível na v1.0, use o seletor Versão.

As APIs de educação no Microsoft Graph melhoram os recursos e os dados do Microsoft 365 com informações relevantes para cenários de educação, incluindo escolas, estudantes, professores, turmas, inscrições e tarefas. Isso facilita a criação de soluções que se integram aos recursos educacionais.

As APIs de educação incluem recursos de lista e recursos de tarefas que pode utilizar para interagir com os serviços de lista e atribuição no Microsoft Teams. Pode utilizar estes recursos para gerir uma lista escolar e automatizar as tarefas dos estudantes.

Authorization

Para chamar as APIs de educação no Microsoft Graph, a sua aplicação tem de adquirir um token de acesso. Para obter detalhes sobre tokens de acesso, confira Obter tokens de acesso para chamar o Microsoft Graph. A sua aplicação também precisa das permissões adequadas. 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 acionar uma caixa de diálogo de consentimento, utilize a seguinte chamada REST.

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

Trabalho de turma

Pode utilizar o Classwork como uma loja única para criar e organizar recursos da turma, incluindo tarefas, páginas do Blocos de Notas Escolares do OneNote, ligações Web, ficheiros e canais do Teams. Isto significa que já não tem de navegar em várias aplicações e plataformas para encontrar o que precisa. Com o Trabalho escolar, pode organizar uma vista de conteúdos e recursos que ajudam os seus alunos a navegar na turma e a ver tudo num único local.

A API classwork fornece os seguintes recursos principais:

• educationModule – um módulo está associado a uma turma. Representa um grupo de recursos de aprendizagem individuais organizados de forma sistemática.
• educationModuleResource – um objeto de wrapper que armazena os recursos associados a um módulo. O estudante não consegue atualizar este recurso, que é um folheto do professor para o estudante sem ter de entregar nada.

As listas seguintes mostram os cenários suportados pela API classwork.

Módulos

O recurso educationModule suporta os seguintes cenários:

• Listar módulos
• Criar módulo
• Obter módulo
• Atualizar módulo
• Eliminar módulo
• Módulo Afixar
• Remover módulo
• Publicar módulo
• Configurar a pasta de recursos do módulo

Recursos do módulo

O recurso educationModuleResource suporta os seguintes cenários:

• Listar recursos do módulo
• Criar recurso do módulo
• Obter recurso do módulo
• Atualizar recurso do módulo
• Eliminar recurso do módulo

Casos de uso comuns

A tabela seguinte mostra alguns casos de utilização comuns para as APIs de educação relacionadas com o módulo.

Caso de uso	Descrição	Veja também
Criar um módulo	Apenas os professores numa turma podem criar um módulo. Os módulos começam no estado de rascunho, o que significa que os estudantes não veem os módulos até à publicação.	Criar educationModule
Listar módulos	Um professor ou uma aplicação com permissões de aplicação pode ver todos os objetos de módulo da turma. Os estudantes só podem ver módulos publicados.	Listar módulos de classe
Publicar um módulo	Altera o estado de um educationModule do respetivo estado original draft para o published estado.	educationModule: publicar
Criar um recurso num módulo	Apenas os professores podem efetuar esta operação.	Criar educationModuleResource
Listar recursos do módulo	Obtenha todos os objetos educationModuleResource associados a um módulo. Apenas professores, estudantes e aplicações com permissões de aplicação podem realizar esta operação.	Listar recursos do módulo

Gestão da sincronização de dados da escola

O School Data Sync ajuda a automatizar o processo de importação e sincronização de dados de lista de sistemas de informação de estudantes com o Microsoft Entra ID e o Microsoft 365. Pode utilizar as APIs de gestão de sincronização de dados escolares no Microsoft Graph para configurar a sincronização a partir de um ficheiro CSV ou de um conector de API do SIS suportado.

As APIs de gestão de sincronização de dados escolares suportam os seguintes cenários:

• Listar perfis de sincronização
• Obter perfil de sincronização
• Criar perfil de sincronização
• Eliminar perfil de sincronização
• Colocar em pausa uma sincronização contínua
• Retomar uma sincronização em pausa
• Repor uma sincronização
• Iniciar a sincronização para ficheiros carregados
• Obter um URL de carregamento
• Obter o estado de uma sincronização
• Obter erros de sincronização

Próximas etapas

Utilize as APIs de educação do Microsoft Graph para criar soluções de educação que acedam a tarefas de estudantes e listas escolares. Para saber mais:

• Explore os recursos e os métodos mais úteis para seu cenário.
• Experimente a API no Explorador do Graph.