Use a API de dados do setor como um mecanismo ETL (extração, transformação e carga) (versão prévia)
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.
A API de dados do setor é uma plataforma etl focada no setor de educação (Extração-Transformação-Carga) que combina dados de várias fontes em um único armazenamento de dados do Azure Data Lake, normaliza os dados e os exporta em fluxos de saída. A API fornece recursos que você pode usar para obter estatísticas após o processamento dos dados e ajudar no monitoramento e solução de problemas.
A API de dados do setor é definida no subnamespace microsoft.graph.industryDataOData .
API e educação de dados do setor
A API de dados do setor alimenta a plataforma Microsoft School Data Sync (SDS) para ajudar a automatizar o processo de importação de dados e sincronização de organizações, usuários e associações de usuários e grupos com Microsoft Entra ID e Microsoft 365 dos sistemas de informações estudantis (SIS) e sistemas de gerenciamento de alunos (SMS). Depois de normalizar os dados, a API utiliza os dados por meio de vários fluxos de provisionamento de saída para gerenciar usuários, grupos de classes, unidades administrativas e grupos de segurança.
Primeiro, você se conecta aos dados da sua instituição. Para definir um fluxo de entrada, crie uma fonteSystemDefinition, dataConnector e yearTimePeriodDefinition. Por padrão, o fluxo de entrada é ativado duas vezes (2x) diariamente (chamado de execução).
Quando a execução é iniciada, ela se conecta ao sourceSystemDefinition e ao dataConnector do fluxo de entrada e executa a validação básica. A validação básica garante que a conexão esteja correta, quando a API OneRoster for a origem ou os nomes de arquivo e cabeçalhos estiverem corretos quando um CSV for a origem.
Em seguida, o sistema transforma os dados para importação em preparação para validação avançada. Como parte da transformação de dados, os dados são associados com base no ano configuradoTimePeriodDefinition.
O sistema armazena a cópia mais recente do Microsoft Entra ID do locatário no Azure Data Lake. A cópia do Microsoft Entra ajuda na correspondência do usuário entre o sourceSystemDefinition e o objeto Microsoft Entra usuário. Nesta fase, o link de correspondência é gravado apenas no Azure Data Lake.
Em seguida, o fluxo de entrada executa validação avançada para determinar a integridade dos dados. A validação se concentra na identificação de erros e avisos para garantir que bons dados entrem e os dados ruins permaneçam fora. Erros indicam que um registro não passou pela validação e foi removido do processamento adicional. Avisos indicam que o valor em um campo opcional de um registro não passou. O valor é removido do registro, mas o registro é incluído para processamento adicional.
Erros e avisos ajudam você a entender melhor a integridade dos dados.
Para os dados que passaram pela validação, o processo usa o yearTimePeriodDefinition configurado para determinar sua associação para armazenamento longitudinal, da seguinte maneira:
- Como os dados são armazenados a representação interna no Azure Data Lake do locatário, ele identifica quando foi visto pela primeira vez pelos dados do setor.
- Para dados vinculados a uma organização de usuário, associação de função e associação de grupo, ele também identifica dados como ativos na sessão com base no anoTimePeriodDefinition.
- Em execuções futuras, para o mesmo fluxo de entrada, sourceSystemDefinition e yearTimePeriodDefinition, os dados do setor identificam se o registro ainda é visto.
- Com base na presença ou ausência de registro, o registro é mantido ativo ou marcado como não mais ativo na sessão para o ano configuradoTimePeriodDefinition. Esse processo determina a natureza histórica e longitudinal dos dados entre dias, meses e anos.
No final de cada execução, industryDataRunStatistics estão disponíveis para determinar a integridade dos dados.
Erros e avisos relacionados ao industryDataRunStatistics são produzidos para ajudar a fornecer uma compreensão inicial da integridade dos dados. Quando você investiga a integridade dos dados, os dados do setor fornecem a capacidade de baixar um arquivo de log que contém informações com base nos erros e avisos encontrados para iniciar o processo de investigação de dados para corrigir os dados no sistema de origem.
Depois de investigar e resolver quaisquer erros ou avisos de dados, quando estiver confortável com o estado atual da integridade dos dados, você poderá habilitar os cenários com os dados. Quando você habilita um cenário para usar esses dados, o cenário cria um fluxo de provisionamento de saída.
O gerenciamento de dados por meio de fluxos de provisionamento de saída simplifica o gerenciamento de usuários e classes. Somente usuários ativos e compatíveis são incluídos nos dados usados para gravar o link no objeto Microsoft Entra usuário. Esse link facilita a integração entre o SIS/SMS e suas seções para grupos e salas de aula do Microsoft Teams.
Para obter mais informações, confira as seções Sincronização de Dados Escolares, pré-requisitos do SDS e conceitos principais do SDS da visão geral de Sincronização de Dados Escolares.
Registro, permissões e autorização
Você pode integrar APIs de dados do setor a aplicativos de terceiros. Para obter detalhes sobre como fazer isso, confira os seguintes artigos:
- Noções básicas de autenticação e autorização.
- Registre um aplicativo com o plataforma de identidade da Microsoft.
- Obtenha acesso em nome de um usuário.
- Referência de permissões do Microsoft Graph.
- Resolva erros de autorização do Microsoft Graph.
Casos de uso comuns
| Caso de uso | Recurso REST | Confira também |
|---|---|---|
| Criar uma atividade para importar um conjunto de dados delimitado | inboundFileFlow | métodos inboundFileFlow |
| Definir uma fonte de dados de entrada | sourceSystemDefinition | métodos sourceSystemDefinition |
| Criar um conector para postar dados em um Azure Data Lake (se CSV) | azureDataLakeConnector | métodos azureDataLakeConnector |
Domínio de dados
A propriedade dataDomain define o tipo de dados importados e determina o formato de modelo de dados comum para que ele seja armazenado. Atualmente, o único dataDomain com suporte é educationRostering.
Definições de referência
Uma referênciaDefinition representa um valor enumerado. Cada domínio do setor com suporte recebe uma coleção distinta de definições. os recursos referenceDefinition são usados extensivamente em todo o sistema, tanto para configuração quanto para transformação, em que os valores potenciais são específicos para um determinado setor. Cada referênciaDefinition usa um identificador composto de {referenceType}-{code} para fornecer uma experiência consistente entre os locatários do cliente.
Valores de referência
Tipos baseados em referenceValue fornecem uma experiência de desenvolvedor simplificada para referência de associaçãoDefinição de recursos. Cada tipo referenceValue está associado a um único tipo de referência, permitindo que os desenvolvedores forneçam apenas a parte de código da definição de referência como uma cadeia de caracteres simples e eliminando possíveis confusão quanto a qual tipo de referênciaDefinition uma determinada propriedade é esperada.
Exemplo
A propriedade userMatchingSettings.sourceIdentifier usa um tipo identifierTypeReferenceValue que se associa ao RefIdentifierTypereferenceType.
"sourceIdentifier": {
"code": "username"
},
Uma referênciaDefinition também pode estar vinculada diretamente usando a propriedade value .
"sourceIdentifier": {
"value@odata.bind": "external/industryData/referenceDefinitions/RefIdentifierType-username"
},
Grupos de função
A transformação dos dados geralmente é moldada pela função de cada usuário individual dentro de uma organização. Essas funções são definidas como definições de referência. Dado o número de funções potenciais, associar cada indivíduo de função resultaria em uma experiência de usuário tediosa. Os grupos de funções são uma coleção de RefRole códigos.
{
"@odata.type": "#microsoft.graph.industryDataRoleGroup",
"id": "37a9781b-db61-4a3c-a3c1-8cba92c9998e",
"displayName": "Staff",
"roles": [
{ "code": "adjunct" },
{ "code": "administrator" },
{ "code": "advisor" },
{ "code": "affiliate" },
{ "code": "aide" },
{ "code": "alumni" },
{ "code": "assistant" }
]
}
Conectores de dados do setor
Um industryDataConnector atua como uma ponte entre uma fonteSystemDefinition e um Fluxo de Entrada. Ele é responsável por adquirir dados de uma fonte externa e fornecer os dados para fluxos de dados de entrada.
Carregar e validar dados CSV
Para obter informações sobre dados CSV, consulte:
Veja a seguir os requisitos para o arquivo CSV:
- Nomes de arquivo e cabeçalhos de coluna são sensíveis a maiúsculas de minúsculas.
- Os arquivos CSV devem estar no formato UTF-8.
- Os dados de entrada não devem ter quebras de linha.
Para examinar e baixar o conjunto de exemplos de arquivos CSV do SDS V2.1, consulte o repositório SDS GitHub.
Importante
O industryDataConnector não aceita alterações delta, portanto, cada sessão de upload deve conter o conjunto de dados completo. Fornecer apenas dados parciais ou delta resulta na transição de quaisquer registros ausentes para um estado inativo.
Solicitar uma sessão de upload
O azureDataLakeConnector usa arquivos CSV carregados em um contêiner seguro. Esse contêiner vive no contexto de um único arquivoUploadSession e é destruído automaticamente após a validação de dados ou a sessão de carregamento de arquivo expirar.
A sessão de carregamento de arquivo atual é recuperada de um azureDataLakeConnector por meio do getUploadSession que retorna a URL SAS para carregar os arquivos CSV.
Validar arquivos carregados
Os arquivos de dados carregados devem ser validados antes que um fluxo de entrada possa processar os dados. O processo de validação finaliza o arquivo atualUploadSession e verifica se todos os arquivos necessários estão presentes e formatados corretamente. A validação é iniciada chamando o industryDataConnector: validar a ação do recurso azureDataLakeConnector .
A ação de validação cria um arquivo de execução longaValidateOperation. O URI do arquivoValidateOperation é fornecido no Location cabeçalho da resposta. Você pode usar esse URI para controlar o status da operação de longa execução e quaisquer erros ou avisos criados durante a validação.
Próximas etapas
Use as APIs de dados do setor do Microsoft Graph como um mecanismo ETL (extração, transformação e carga). Para saber mais:
- Explore os recursos e os métodos mais úteis para seu cenário.
- Experimente a API no Explorador do Graph.
Conteúdo relacionado
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de