将行业数据 API 用作提取、转换和加载 (ETL) 引擎 (预览)

重要

Microsoft Graph /beta 版本下的 API 可能会发生更改。 不支持在生产应用程序中使用这些 API。 若要确定 API 是否在 v1.0 中可用,请使用 版本 选择器。

行业数据 API 是一个侧重于教育行业的 ETL (提取-转换-加载) 平台,它将来自多个源的数据合并到单个 Azure Data Lake 数据存储中,规范化数据,并在出站流中导出数据。 API 提供可用于在处理数据后获取统计信息的资源,并有助于监视和故障排除。

行业数据 API 在 OData 子名称空间 microsoft.graph.industryData中定义。

行业数据 API 和教育

行业数据 API 为 Microsoft School Data Sync (SDS) 平台提供支持,以帮助自动导入数据,并同步具有 Microsoft Entra ID 和 Microsoft 365 的学生信息系统 (SIS) 和学生管理系统 (短信) 的组织、用户和用户关联以及组的过程。 规范化数据后,API 通过多个出站预配流利用数据来管理用户、类组、管理单元和安全组。

行业数据 ETL 流程图示

首先,连接到机构的数据。 若要定义入站流,请创建 sourceSystemDefinitiondataConnectoryearTimePeriodDefinition。 默认情况下,入站流每天激活两次 (2 倍) (称为 运行) 。

运行开始时,它会连接到入站流的 sourceSystemDefinitiondataConnector ,并执行基本验证。 当 OneRoster API 是源时,基本验证可确保连接正确,或者当 CSV 为源时,文件名和标头正确。

接下来,系统会转换要导入的数据,为高级验证做准备。 作为数据转换的一部分,数据基于配置的 yearTimePeriodDefinition 进行关联。

系统将租户Microsoft Entra ID 的最新副本存储在 Azure Data Lake 中。 Microsoft Entra 的副本有助于 在 sourceSystemDefinition 和 Microsoft Entra 用户对象之间进行用户匹配。 在此阶段,匹配链接仅写入 Azure Data Lake。

接下来,入站流执行高级验证以确定数据运行状况。 验证侧重于识别错误和警告,以确保好数据传入,而错误数据会留下来。错误指示记录未通过验证,并且已从进一步处理中删除。 警告指示记录的可选字段上的值未传递。 该值将从记录中删除,但包含记录以供进一步处理。

错误和警告有助于更好地了解数据运行状况。

对于通过验证的数据,该过程使用配置的 yearTimePeriodDefinition 来确定其纵向存储关联,如下所示:

  • 由于数据存储在租户的 Azure Data Lake 中的内部表示形式,因此它标识行业数据首次看到数据时。
  • 对于与用户组织、角色关联和组关联链接的数据,它还根据 yearTimePeriodDefinition 将数据标识为会话中的活动数据。
  • 在将来的运行中,对于同一入站流、 sourceSystemDefinitionyearTimePeriodDefinition,行业数据标识是否仍会看到该记录。
  • 根据是否存在记录,记录将保持活动状态或标记为不再在配置的 yearTimePeriodDefinition 的会话中处于活动状态。 此过程确定数据在天、月和年之间的历史和纵向性质。

每次运行结束时, industryDataRunStatistics 可用于确定数据运行状况。

生成与 industryDataRunStatistics 相关的错误和警告,以帮助初步了解数据运行状况。 调查数据运行状况时,行业数据提供下载日志文件的功能,该文件包含基于发现的错误和警告的信息,以开始数据调查过程以更正源系统中的数据。

调查并解决任何数据错误或警告后,当你熟悉数据运行状况的当前状态时,可以使用数据启用方案。 启用方案以使用此数据时,该方案将创建出站预配流。

通过出站预配流管理数据简化了对用户和类的管理。 只有活动用户和匹配的用户包含在用于将链接写入到 Microsoft Entra 用户对象的数据中。 此链接可促进 SIS/SMS 及其组和Microsoft Teams 课堂分区之间的集成。

有关详细信息,请参阅学校数据同步概述的学校 数据同步、SDS 先决条件和 SDS 核心概念部分。

注册、权限和授权

可以将行业数据 API 与第三方应用集成。 有关如何执行此操作的详细信息,请参阅以下文章:

常见用例

用例 REST 资源 另请参阅
创建活动以导入带分隔符的数据集 inboundFileFlow inboundFileFlow 方法
定义入站数据源 sourceSystemDefinition sourceSystemDefinition 方法
创建连接器以将数据发布到 Azure Data Lake ((如果 CSV) ) azureDataLakeConnector azureDataLakeConnector 方法

数据域

dataDomain 属性定义导入的数据类型,并确定存储数据的通用数据模型格式。 目前,唯一受支持的 dataDomaineducationRostering

引用定义

referenceDefinition 表示枚举值。 每个受支持的行业域都接收不同的定义集合。 referenceDefinition 资源在整个系统中广泛使用,用于配置和转换,其中的潜在值特定于给定行业。 每个 referenceDefinition 使用 的 {referenceType}-{code} 复合标识符来跨客户租户提供一致的体验。

引用值

基于 referenceValue 的类型为绑定 referenceDefinition 资源提供了简化的开发人员体验。 每个 referenceValue 类型都绑定到单个引用类型,使开发人员能够仅将引用定义的 代码 部分作为简单字符串提供,并消除了有关给定属性预期为哪种 类型的 referenceDefinition 的潜在混淆。

示例

userMatchingSettings.sourceIdentifier 属性采用绑定到 RefIdentifierTypereferenceTypeidentifierTypeReferenceValue 类型。

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

还可以使用 value 属性直接绑定 referenceDefinition

"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 充当 sourceSystemDefinitioninboundFlow 之间的桥梁。 它负责从外部源获取数据,并将数据提供给入站数据流。

上传和验证 CSV 数据

有关 CSV 数据的信息,请参阅:

以下是 CSV 文件的要求:

  • 文件名和列标题区分大小写。
  • CSV 文件必须采用 UTF-8 格式。
  • 传入数据不得有换行符。

若要查看和下载 SDS V2.1 CSV 文件的示例集,请参阅 SDS GitHub 存储库

重要

industryDataConnector 不接受增量更改,因此每个上传会话都必须包含完整的数据集。 仅提供部分或增量数据会导致任何缺失记录转换为非活动状态。

请求上传会话

azureDataLakeConnector 使用上传到安全容器的 CSV 文件。 此容器位于单个 fileUploadSession 的上下文中,并在数据验证或文件上传会话过期后自动销毁。

当前文件上传会话通过 getUploadSessionazureDataLakeConnector 中检索,该 getUploadSession 返回用于上传 CSV 文件的 SAS URL。

验证上传的文件

必须先验证上传的数据文件,然后入站流才能处理数据。 验证过程完成当前 fileUploadSession 并验证所有必需的文件是否存在并正确设置了格式。 验证通过调用 industryDataConnector:验证azureDataLakeConnector 资源的操作来启动。

验证操作创建一个长时间运行的文件ValidateOperation。 响应标头中Location提供了 fileValidateOperation 的 URI。 可以使用此 URI 跟踪长时间运行的操作的状态,以及验证期间创建的任何错误或警告。

后续步骤

使用 Microsoft Graph 行业数据 API 作为提取、转换和加载 (ETL) 引擎。 了解详细信息:

  • 探索对你的方案最有帮助的资源和方法。
  • 尝试在 Graph 浏览器中使用 API。

Microsoft Graph 中的行业数据 API 概述