Использование API отраслевых данных в качестве подсистемы извлечения, преобразования и загрузки (ETL) (предварительная версия)
Важно!
API версии /beta в Microsoft Graph могут быть изменены. Использование этих API в производственных приложениях не поддерживается. Чтобы определить, доступен ли API в версии 1.0, используйте селектор версий.
API отраслевых данных — это платформа ETL (Извлечение,преобразование-загрузка), ориентированная на образование, которая объединяет данные из нескольких источников в одно хранилище данных Azure Data Lake, нормализует данные и экспортирует их в исходящих потоках. API предоставляет ресурсы, которые можно использовать для получения статистики после обработки данных, а также для помощи в мониторинге и устранении неполадок.
API отраслевых данных определяется в подпространстве microsoft.graph.industryDataимен OData .
API отраслевых данных и образования
API отраслевых данных использует платформу Microsoft School Data Sync (SDS) для автоматизации процесса импорта данных и синхронизации организаций, пользователей и ассоциаций пользователей, а также групп с помощью Идентификатора Microsoft Entra и Microsoft 365 из информационных систем учащихся (SIS) и систем управления учащимися (SMS). После нормализации данных API использует данные через несколько потоков исходящей подготовки для управления пользователями, группами классов, административными единицами и группами безопасности.
Во-первых, вы подключаетесь к данным вашего учреждения. Чтобы определить входящий поток, создайте sourceSystemDefinition, dataConnector и yearTimePeriodDefinition. По умолчанию входящий поток активируется дважды (2 раза) в день (называется выполнением).
При запуске запуска он подключается к sourceSystemDefinition и dataConnector входящего потока и выполняет базовую проверку. Базовая проверка гарантирует правильность подключения, когда источником является API OneRoster , или имена файлов и заголовки верны, если csv-файл является источником.
Затем система преобразует данные для импорта в рамках подготовки к расширенной проверке. В рамках преобразования данных данные связываются на основе настроенного параметра yearTimePeriodDefinition.
Система сохраняет последнюю копию идентификатора Microsoft Entra клиента в 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 отраслевых данных можно интегрировать со сторонними приложениями. Дополнительные сведения о том, как это сделать, см. в следующих статьях:
- Основы проверки подлинности и авторизации.
- Зарегистрируйте приложение на платформе удостоверений Майкрософт.
- Получение доступа от имени пользователя.
- Справочник по разрешениям Microsoft Graph.
- Устранение ошибок авторизации Microsoft Graph.
Основные варианты использования
| Вариант использования | Ресурс 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.