将行业数据 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 通过多个出站预配流利用数据来管理用户、类组、管理单元和安全组。
首先，连接到机构的数据。 若要定义入站流，请创建 sourceSystemDefinition、 dataConnector 和 yearTimePeriodDefinition。 默认情况下，入站流每天激活两次 (2 倍) (称为 运行) 。
运行开始时，它会连接到入站流的 sourceSystemDefinition 和 dataConnector ，并执行基本验证。 当 OneRoster API 是源时，基本验证可确保连接正确，或者当 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 课堂分区之间的集成。
有关详细信息，请参阅学校数据同步概述的学校 数据同步、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 属性采用绑定到 RefIdentifierTypereferenceType 的 identifierTypeReferenceValue 类型。
"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 充当 sourceSystemDefinition 和 inboundFlow 之间的桥梁。 它负责从外部源获取数据，并将数据提供给入站数据流。
上传和验证 CSV 数据
有关 CSV 数据的信息，请参阅：
以下是 CSV 文件的要求：
- 文件名和列标题区分大小写。
- CSV 文件必须采用 UTF-8 格式。
- 传入数据不得有换行符。
若要查看和下载 SDS V2.1 CSV 文件的示例集，请参阅 SDS GitHub 存储库。
重要
industryDataConnector 不接受增量更改，因此每个上传会话都必须包含完整的数据集。 仅提供部分或增量数据会导致任何缺失记录转换为非活动状态。
请求上传会话
azureDataLakeConnector 使用上传到安全容器的 CSV 文件。 此容器位于单个 fileUploadSession 的上下文中，并在数据验证或文件上传会话过期后自动销毁。
当前文件上传会话通过 getUploadSession 从 azureDataLakeConnector 中检索，该 getUploadSession 返回用于上传 CSV 文件的 SAS URL。
验证上传的文件
必须先验证上传的数据文件，然后入站流才能处理数据。 验证过程完成当前 fileUploadSession 并验证所有必需的文件是否存在并正确设置了格式。 验证通过调用 industryDataConnector：验证azureDataLakeConnector 资源的操作来启动。
验证操作创建一个长时间运行的文件ValidateOperation。 响应标头中Location提供了 fileValidateOperation 的 URI。 可以使用此 URI 跟踪长时间运行的操作的状态，以及验证期间创建的任何错误或警告。
后续步骤
使用 Microsoft Graph 行业数据 API 作为提取、转换和加载 (ETL) 引擎。 了解详细信息：
- 探索对你的方案最有帮助的资源和方法。
- 尝试在 Graph 浏览器中使用 API。