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

重要

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

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

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

行业数据 API 和教育

行业数据 API 为 Microsoft 学校数据同步 (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 与第三方应用集成。 有关如何执行此操作的详细信息，请参阅以下文章：

• 身份验证和授权基础知识。
• 向 Microsoft 标识平台 注册应用程序。
• 代表用户获取访问权限。
• 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 属性采用绑定到 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 数据的信息，请参阅：

• 使用 SDS v2.1 CSV 引入数据
  • SDS V2.1 CSV 文件格式
• 使用 SDS v1 CSV 引入数据
  • SDS V1 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。

相关内容

Microsoft Graph 中的行业数据 API 概述