Использование API отраслевых данных в качестве подсистемы извлечения, преобразования и загрузки (ETL) (предварительная версия)

  • Статья

Важно!

API версии /beta в Microsoft Graph могут быть изменены. Использование этих API в производственных приложениях не поддерживается. Чтобы определить, доступен ли API в версии 1.0, используйте селектор версий.

API отраслевых данных — это платформа ETL (Извлечение,преобразование-загрузка), ориентированная на образование, которая объединяет данные из нескольких источников в одно хранилище данных Azure Data Lake, нормализует данные и экспортирует их в исходящих потоках. API предоставляет ресурсы, которые можно использовать для получения статистики после обработки данных, а также для помощи в мониторинге и устранении неполадок.

API отраслевых данных определяется в подпространстве microsoft.graph.industryDataимен OData .

API отраслевых данных и образования

API отраслевых данных предоставляет платформу Синхронизация сведений о школе Microsoft (SDS) для автоматизации процесса импорта данных и синхронизации организаций, пользователей и ассоциаций пользователей, а также групп с Microsoft Entra ID и Microsoft 365 из информационных систем учащихся (SIS) и систем управления учащимися (SMS). После нормализации данных API использует данные через несколько потоков исходящей подготовки для управления пользователями, группами классов, административными единицами и группами безопасности.

Иллюстрация процесса извлечения отраслевых данных

Во-первых, вы подключаетесь к данным вашего учреждения. Чтобы определить входящий поток, создайте sourceSystemDefinition, dataConnector и yearTimePeriodDefinition. По умолчанию входящий поток активируется дважды (2 раза) в день (называется выполнением).

При запуске запуска он подключается к sourceSystemDefinition и dataConnector входящего потока и выполняет базовую проверку. Базовая проверка гарантирует правильность подключения, когда источником является API OneRoster , или имена файлов и заголовки верны, если csv-файл является источником.

Затем система преобразует данные для импорта в рамках подготовки к расширенной проверке. В рамках преобразования данных данные связываются на основе настроенного параметра yearTimePeriodDefinition.

Система сохраняет последнюю копию Microsoft Entra ID клиента в Azure Data Lake. Копия Microsoft Entra помогает с сопоставлением пользователей между sourceSystemDefinition и объектом пользователя Microsoft Entra. На этом этапе ссылка на соответствие записывается только в Azure Data Lake.

Затем входящий поток выполняет расширенную проверку для определения работоспособности данных. Проверка сосредоточена на выявлении ошибок и предупреждений, чтобы гарантировать, что хорошие данные поступают, а плохие данные остаются вне. Ошибки указывают на то, что запись не прошла проверку и была удалена из дальнейшей обработки. Предупреждения указывают на то, что значение необязательного поля записи не прошло. Значение удаляется из записи, но запись включается для дальнейшей обработки.

Ошибки и предупреждения помогают лучше понять работоспособности данных.

Для данных, прошедших проверку, процесс использует настроенное значение yearTimePeriodDefinition для определения их связи с продольным хранилищем следующим образом:

  • Поскольку данные хранятся во внутреннем представлении в Azure Data Lake клиента, они определяют, когда они были впервые замечены отраслевыми данными.
  • Для данных, связанных с организацией пользователя, связью ролей и ассоциацией групп, она также определяет данные как активные в сеансе на основе yearTimePeriodDefinition.
  • В будущих запусках для того же входящего потока, sourceSystemDefinition и yearTimePeriodDefinition отраслевые данные определяют, отображается ли запись.
  • В зависимости от наличия или отсутствия записи запись сохраняется активной или помечается как неактивная в сеансе для настроенного yearTimePeriodDefinition. Этот процесс определяет исторический и продольный характер данных между днями, месяцами и годами.

В конце каждого запуска доступны данные industryDataRunStatistics для определения работоспособности данных.

Ошибки и предупреждения, связанные с industryDataRunStatistics , создаются для обеспечения первоначального понимания работоспособности данных. При анализе работоспособности данных отраслевые данные позволяют скачать файл журнала, содержащий сведения на основе обнаруженных ошибок и предупреждений, чтобы начать процесс исследования данных для исправления данных в исходной системе.

После изучения и устранения ошибок или предупреждений данных, когда вы будете удовлетворены текущим состоянием работоспособности данных, вы можете включить сценарии с данными. При включении сценария для использования этих данных сценарий создает поток исходящей подготовки.

Управление данными с помощью потоков исходящей подготовки упрощает управление пользователями и классами. В данные, используемые для записи ссылки на объект Microsoft Entra пользователя, включаются только активные и совпадающие пользователи. Эта ссылка упрощает интеграцию между SIS/SMS и их разделами для групп и аудиторий Microsoft Teams.

Дополнительные сведения см. в разделах School Data Sync, предварительные требования SDS и основные понятия SDS в обзоре Службы синхронизации данных школы.

Регистрация, разрешения и авторизация

Api отраслевых данных можно интегрировать со сторонними приложениями. Дополнительные сведения о том, как это сделать, см. в следующих статьях:

Основные варианты использования

Вариант использования Ресурс REST См. также
Создание действия для импорта набора данных с разделителями inboundFileFlow методы inboundFileFlow
Определение источника входящих данных sourceSystemDefinition Методы sourceSystemDefinition
Создание соединителя для публикации данных в Azure Data Lake (если CSV) azureDataLakeConnector Методы azureDataLakeConnector

Домен данных

Свойство dataDomain определяет тип импортируемых данных и общий формат модели данных для их хранения. В настоящее время единственным поддерживаемым dataDomain является educationRostering.

Определения ссылок

ReferenceDefinition представляет перечисленное значение. Каждый поддерживаемый отраслевой домен получает отдельную коллекцию определений. Ресурсы referenceDefinition широко используются в системе как для конфигурации, так и для преобразования, где потенциальные значения относятся к конкретной отрасли. Каждое referenceDefinition использует составной идентификатор для {referenceType}-{code} обеспечения согласованного взаимодействия между клиентами.

Ссылочные значения

Типы, основанные на referenceValue, предоставляют упрощенный интерфейс разработчика для привязки ресурсов referenceDefinition . Каждый тип referenceValue привязан к одному ссылочному типу, что позволяет разработчикам предоставлять только часть кода определения ссылки в виде простой строки и устраняет потенциальную путаницу в отношении того, какой тип referenceDefinition ожидается для данного свойства.

Пример

Свойство userMatchingSettings.sourceIdentifier принимает тип identifierTypeReferenceValue , который привязывается к RefIdentifierTypereferenceType.

"sourceIdentifier": {
    "code": "username"
},

Свойство referenceDefinition также может быть привязано непосредственно с помощью свойства value.

"sourceIdentifier": {
    "value@odata.bind": "external/industryData/referenceDefinitions/RefIdentifierType-username"
},

Группы ролей

Преобразование данных часто формируется ролью каждого отдельного пользователя в организации. Эти роли определяются как эталонные определения. Учитывая количество потенциальных ролей, привязка каждой отдельной роли приведет к емкому взаимодействию с пользователем. Группы ролей — это коллекция кодов RefRole .

{
  "@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" }
  ]
}

Отраслевые соединители данных

IndustryDataConnector выступает в качестве моста между sourceSystemDefinition и inboundFlow. Он отвечает за получение данных из внешнего источника и предоставление данных входящим потокам данных.

Отправка и проверка данных CSV

Сведения о данных CSV см. в разделе:

Ниже приведены требования к CSV-файлу.

  • В именах файлов и заголовках столбцов учитывается регистр.
  • CSV-файлы должны быть в формате UTF-8.
  • Входящие данные не должны иметь разрывов строк.

Чтобы просмотреть и скачать пример набора CSV-файлов SDS версии 2.1, см. репозиторий SDS GitHub.

Важно!

IndustryDataConnector не принимает разностные изменения, поэтому каждый сеанс отправки должен содержать полный набор данных. Предоставление только частичных или разностных данных приводит к переходу всех отсутствующих записей в неактивное состояние.

Запрос сеанса отправки

AzureDataLakeConnector использует CSV-файлы, отправленные в безопасный контейнер. Этот контейнер находится в контексте одного файлаUploadSession и автоматически уничтожается после проверки данных или истечения срока действия сеанса отправки файлов.

Текущий сеанс отправки файлов извлекается из azureDataLakeConnector через getUploadSession , который возвращает URL-адрес SAS для отправки CSV-файлов.

Проверка отправленных файлов

Отправленные файлы данных должны быть проверены, прежде чем входящий поток сможет обработать данные. Процесс проверки завершает работу с текущим файломUploadSession и проверяет наличие всех необходимых файлов и их правильное форматирование. Проверка инициируется путем вызова действия industryDataConnector: validate ресурса azureDataLakeConnector .

Действие проверки создает длительный файлValidateOperation. Универсальный код ресурса (URI) для fileValidateOperation указан в заголовке Location ответа. Этот универсальный код ресурса (URI) можно использовать для отслеживания состояния длительно выполняющейся операции и любых ошибок или предупреждений, созданных во время проверки.

Дальнейшие действия

Используйте API отраслевых данных Microsoft Graph в качестве подсистемы извлечения, преобразования и загрузки (ETL). Чтобы узнать больше:

  • Изучите ресурсы и методы, наиболее полезные для вашего сценария.
  • опробуйте API в песочнице Graph.

Связанные материалы

Обзор API отраслевых данных в Microsoft Graph