使用 Azure 数据工厂或 Synapse Analytics 向/从 Azure 数据资源管理器复制数据

项目
07/12/2024

适用于： Azure 数据工厂 Azure Synapse Analytics

提示

试用 Microsoft Fabric 中的数据工厂，这是一种适用于企业的一站式分析解决方案。 Microsoft Fabric 涵盖从数据移动到数据科学、实时分析、商业智能和报告的所有内容。了解如何免费开始新的试用！

本文介绍如何使用 Azure 数据工厂和 Synapse Analytics 管道中的复制活动向/从 Azure 数据资源管理器复制数据。本文是在总体概述复制活动的复制活动概述一文的基础之上编写的。

提示

若要详细了解 Azure 数据资源管理器如何与服务集成，请参阅集成 Azure 数据资源管理器。

支持的功能

以下功能支持此 Azure 数据资源管理器连接器：

支持的功能	IR
复制活动（源/接收器）	① ②
映射数据流源（源/接收器）	①
Lookup 活动	① ②

① Azure 集成运行时 ② 自承载集成运行时

可以将数据从任何受支持的源数据存储复制到 Azure 数据资源管理器。可以将数据从 Azure 数据资源管理器复制到任何受支持的接收器数据存储。有关复制活动支持作为源或接收器的数据存储的列表，请参阅支持的数据存储表。

注意

版本 3.14 和更高版本支持使用自承载集成运行时通过本地数据存储向/从 Azure 数据资源管理器复制数据。

使用 Azure 数据资源管理器连接器可执行以下操作：

通过将 Microsoft Entra 应用程序令牌身份验证与服务主体配合使用来复制数据。
作为源时，请使用 KQL (Kusto) 查询来检索数据。
作为接收器时，请将数据追加到目标表。

入门

提示

有关此 Azure 数据资源管理器连接器概览，请参阅向/从 Azure 数据资源管理器复制数据以及将数据从数据库大容量复制到 Azure 数据资源管理器。

若要使用管道执行复制活动，可以使用以下工具或 SDK 之一：

使用 UI 创建指向 Azure 数据资源管理器的链接服务

使用以下步骤在 Azure 门户 UI 中创建指向 Azure 数据资源管理器的链接服务。

浏览到 Azure 数据工厂或 Synapse 工作区中的“管理”选项卡并选择“链接服务”，然后单击“新建”：
- Azure 数据工厂
- Azure Synapse
搜索资源管理器并选择 Azure 数据资源管理器 (Kusto) 连接器。
配置服务详细信息、测试连接并创建新的链接服务。

连接器配置详细信息

对于特定于 Azure 数据资源管理器连接器的实体，以下部分提供了有关用于定义这些实体的属性的详细信息。

链接服务属性

Azure 数据资源管理器连接器支持以下身份验证类型。请参阅相应部分的了解详细信息：

服务主体身份验证
系统分配的托管标识身份验证
用户分配的托管标识身份验证

服务主体身份验证

若要使用服务主体身份验证，请按照以下步骤获取服务主体并授予权限：

将应用程序注册到 Microsoft 标识平台。快速入门：通过 Microsoft 标识平台注册应用程序。记下以下值，这些值用于定义链接服务：
- 应用程序 ID
- 应用程序密钥
- 租户 ID
在 Azure 数据资源管理器中为服务主体授予正确的权限。有关角色和权限以及管理权限的详细信息，请参阅管理 Azure 数据资源管理器数据库权限。一般情况下，必须授予以下权限：
- 作为源：至少向数据库授予“数据库查看者”角色
- 作为接收器：至少向数据库授予“数据库用户”角色

注意

使用 UI 创作时，登录用户帐户默认用于列出 Azure 数据资源管理器群集、数据库和表。可以选择使用服务主体列出对象，方法是单击“刷新”按钮旁边的下拉列表，或者手动输入名称（如果没有这些操作的权限）。

Azure 数据资源管理器链接服务支持以下属性：

属性	描述	必需
type	type 属性必须设置为 AzureDataExplorer。	是
endpoint	Azure 数据资源管理器群集的终结点 URL，格式为 `https://<clusterName>.<regionName>.kusto.chinacloudapi.cn`。	是
database	数据库的名称。	是
tenant	指定应用程序的租户信息（域名或租户 ID）。此 ID 在 Kusto 连接字符串中称为“颁发机构 ID”。将鼠标指针悬停在 Azure 门户右上角进行检索。	是
servicePrincipalId	指定应用程序的客户端 ID。在 Kusto 连接字符串中，这称为“Microsoft Entra 应用程序客户端 ID”。	是
servicePrincipalKey	指定应用程序的密钥。在 Kusto 连接字符串中，这称为“Microsoft Entra 应用程序密钥”。请将此字段标记为 SecureString 以安全地存储它，或引用存储在 Azure Key Vault 中的安全数据。	是
connectVia	用于连接到数据存储的集成运行时。可使用 Azure Integration Runtime 或自承载集成运行时（如果数据存储位于专用网络）。如果未指定，则使用默认 Azure Integration Runtime。	否

示例：使用服务主体密钥身份验证

{
    "name": "AzureDataExplorerLinkedService",
    "properties": {
        "type": "AzureDataExplorer",
        "typeProperties": {
            "endpoint": "https://<clusterName>.<regionName>.kusto.chinacloudapi.cn",
            "database": "<database name>",
            "tenant": "<tenant name/id e.g. microsoft.partner.onmschina.cn>",
            "servicePrincipalId": "<service principal id>",
            "servicePrincipalKey": {
                "type": "SecureString",
                "value": "<service principal key>"
            }
        }
    }
}

系统分配的托管标识身份验证

若要详细了解 Azure 资源托管标识，请参阅 Azure 资源托管标识。

若要使用系统分配的托管标识身份验证，请按照以下步骤授予权限：

通过复制与工厂或 Synapse 工作区一起生成的“托管标识对象 ID”值，检索托管标识信息。
在 Azure 数据资源管理器中向托管标识授予正确的权限。有关角色和权限以及管理权限的详细信息，请参阅管理 Azure 数据资源管理器数据库权限。一般情况下，必须授予以下权限：
- 作为源：授予对数据库的“数据库查看者”角色。
- 作为接收器：授予对数据库的“数据库引入者”和“数据库查看者”角色。

注意

使用 UI 创作时，登录用户帐户用于列出 Azure 数据资源管理器群集、数据库和表。如果你没有权限执行这些操作，请手动输入名称。

Azure 数据资源管理器链接服务支持以下属性：

属性	描述	必需
type	type 属性必须设置为 AzureDataExplorer。	是
endpoint	Azure 数据资源管理器群集的终结点 URL，格式为 `https://<clusterName>.<regionName>.kusto.chinacloudapi.cn`。	是
database	数据库的名称。	是
connectVia	用于连接到数据存储的集成运行时。可使用 Azure Integration Runtime 或自承载集成运行时（如果数据存储位于专用网络）。如果未指定，则使用默认 Azure Integration Runtime。	否

示例：使用系统分配的托管标识身份验证

{
    "name": "AzureDataExplorerLinkedService",
    "properties": {
        "type": "AzureDataExplorer",
        "typeProperties": {
            "endpoint": "https://<clusterName>.<regionName>.kusto.chinacloudapi.cn",
            "database": "<database name>",
        }
    }
}

用户分配的托管标识身份验证

若要详细了解 Azure 资源托管标识，请参阅 Azure 资源托管标识

若要使用用户分配的托管标识身份验证，请执行以下步骤：

创建一个或多个用户分配的托管标识，并在 Azure 数据资源管理器中授予权限。有关角色和权限以及管理权限的详细信息，请参阅管理 Azure 数据资源管理器数据库权限。一般情况下，必须授予以下权限：
- 作为源：至少向数据库授予“数据库查看者”角色
- 作为接收器：至少向数据库授予“数据库引入者”角色
为数据工厂或 Synapse 工作区分配一个或多个用户分配的托管标识，并为每个用户分配的托管标识创建凭据。

Azure 数据资源管理器链接服务支持以下属性：

属性	描述	必需
type	type 属性必须设置为 AzureDataExplorer。	是
endpoint	Azure 数据资源管理器群集的终结点 URL，格式为 `https://<clusterName>.<regionName>.kusto.chinacloudapi.cn`。	是
database	数据库的名称。	是
凭据	将用户分配的托管标识指定为凭据对象。	是
connectVia	用于连接到数据存储的集成运行时。可使用 Azure Integration Runtime 或自承载集成运行时（如果数据存储位于专用网络）。如果未指定，则使用默认 Azure Integration Runtime。	否

示例：使用用户分配的托管标识身份验证

{
    "name": "AzureDataExplorerLinkedService",
    "properties": {
        "type": "AzureDataExplorer",
        "typeProperties": {
            "endpoint": "https://<clusterName>.<regionName>.kusto.chinacloudapi.cn",
            "database": "<database name>",
            "credential": {
                "referenceName": "credential1",
                "type": "CredentialReference"
            }
        }
    }
}

数据集属性

有关可用于定义数据集的各个部分和属性的完整列表，请参阅数据集。本部分列出了 Azure 数据资源管理器数据集支持的属性。

若要将数据复制到 Azure 数据资源管理器，请将数据集的 type 属性设置为 AzureDataExplorerTable。

支持以下属性：

属性	描述	必需
type	type 属性必须设置为 AzureDataExplorerTable。	是
表	链接服务引用的表的名称。	对于接收器为必需的，对于源不是必需的

数据集属性示例：

{
   "name": "AzureDataExplorerDataset",
    "properties": {
        "type": "AzureDataExplorerTable",
        "typeProperties": {
            "table": "<table name>"
        },
        "schema": [],
        "linkedServiceName": {
            "referenceName": "<Azure Data Explorer linked service name>",
            "type": "LinkedServiceReference"
        }
    }
}

复制活动属性

有关可用于定义活动的各个部分和属性的完整列表，请参阅管道和活动。本部分提供了 Azure 数据资源管理器源和接收器支持的属性列表。

Azure 数据资源管理器作为源

若要从 Azure 数据资源管理器复制数据，请将复制活动源中的 type 属性设置为 AzureDataExplorerSource。复制活动source部分支持以下属性：

属性	描述	必需
type	复制活动源的 type 属性必须设置为：AzureDataExplorerSource	是
查询	以 KQL 格式指定的只读请求。使用自定义 KQL 查询作为参考。	是
queryTimeout	查询请求超时前的等待时间。默认值是 10 分钟 (00:10:00)；允许的最大值是 1 小时 (01:00:00)。	否
noTruncation	指示是否截断返回的结果集。默认情况下，结果在出现 500,000 条记录或达到 64 MB 之后将被截断。强烈建议将其截断，以确保活动的正确行为。	否

注意

默认情况下，Azure 数据资源管理器源的大小限制为 500,000 条记录或 64 MB。若要检索所有记录而不截断，可以在查询的开头指定 set notruncation;。有关详细信息，请参阅查询限制。

示例：

"activities":[
    {
        "name": "CopyFromAzureDataExplorer",
        "type": "Copy",
        "typeProperties": {
            "source": {
                "type": "AzureDataExplorerSource",
                "query": "TestTable1 | take 10",
                "queryTimeout": "00:10:00"
            },
            "sink": {
                "type": "<sink type>"
            }
        },
        "inputs": [
            {
                "referenceName": "<Azure Data Explorer input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ]
    }
]

Azure 数据资源管理器作为接收器

若要将数据复制到 Azure 数据资源管理器，请将复制活动接收器中的 type 属性设置为 AzureDataExplorerSink。复制活动接收器部分中支持以下属性：

属性	描述	必需
type	复制活动接收器的 type 属性必须设置为：AzureDataExplorerSink。	是
ingestionMappingName	基于 Kusto 表预先创建的映射的名称。若要将源中的列映射到 Azure 数据资源管理器（适用于所有支持的源存储和格式，包括 CSV/JSON/Avro 格式），可以使用复制活动列映射（按名称隐式映射或按配置显式映射）和/或 Azure 数据资源管理器映射。	否
additionalProperties	一个属性包，可用于指定 Azure 数据资源管理器接收器尚未设置的任何引入属性。具体来说，它可用于指定引入标记。从 Azure 数据资源管理器数据引入文档了解更多信息。	否

示例：

"activities":[
    {
        "name": "CopyToAzureDataExplorer",
        "type": "Copy",
        "typeProperties": {
            "source": {
                "type": "<source type>"
            },
            "sink": {
                "type": "AzureDataExplorerSink",
                "ingestionMappingName": "<optional Azure Data Explorer mapping name>",
                "additionalProperties": {<additional settings for data ingestion>}
            }
        },
        "inputs": [
            {
                "referenceName": "<input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<Azure Data Explorer output dataset name>",
                "type": "DatasetReference"
            }
        ]
    }
]

映射数据流属性

在映射数据流中转换数据时，可以在 Azure 数据资源管理器中读取表以及将数据写入表。有关详细信息，请参阅映射数据流中的源转换和接收器转换。你可以选择使用 Azure 数据资源管理器数据集或内联数据集作为源和接收器类型。

源转换

下表列出了 Azure 数据资源管理器源支持的属性。你可以在“源选项”选项卡中编辑这些属性。

名称	说明	必需	允许的值	数据流脚本属性
表	如果选择“表”作为输入，则在使用内联数据集时，数据流会从在 Azure 数据资源管理器数据集或源选项中指定的表中获取所有数据。	否	字符串	（仅适用于内联数据集） tableName
查询	以 KQL 格式指定的只读请求。使用自定义 KQL 查询作为参考。	否	字符串	query
超时	查询请求超时前的等待时间。默认值为“172000”（2 天）	否	Integer	timeout

Azure 数据资源管理器源脚本示例

使用 Azure 数据资源管理器数据集作为源类型时，关联的数据流脚本为：

source(allowSchemaDrift: true,
	validateSchema: false,
	query: 'table | take 10',
	format: 'query') ~> AzureDataExplorerSource

如果使用内联数据集，则关联的数据流脚本为：

source(allowSchemaDrift: true,
    validateSchema: false,
    format: 'query',
    query: 'table | take 10',
    store: 'azuredataexplorer') ~> AzureDataExplorerSource

接收器转换

下表列出了 Azure 数据资源管理器接收器支持的属性。可以在“设置”选项卡中编辑这些属性。使用内联数据集时，你会看到其他设置，这些设置与数据集属性部分描述的属性相同。

名称	说明	必需	允许的值	数据流脚本属性
表操作	确定在写入之前是否从目标表重新创建或删除所有行。 - 无：不会对表进行任何操作。 - 重新创建：将删除表并重新创建表。如果以动态方式创建表，则是必需的。 - 截断：将删除目标表中的所有行。	否	`true` 或 `false`	recreate truncate
预处理和后处理 SQL 脚本	指定在将数据写入接收器数据库之前（预处理）和之后（后处理）会执行的多个 Kusto 控制命令脚本。	否	字符串	preSQLs; postSQLs
超时	查询请求超时前的等待时间。默认值为“172000”（2 天）	否	Integer	timeout

Azure 数据资源管理器接收器脚本示例

使用 Azure 数据资源管理器数据集作为接收器类型时，关联的数据流脚本为：

IncomingStream sink(allowSchemaDrift: true,
	validateSchema: false,
	format: 'table',
	preSQLs:['pre SQL scripts'],
	postSQLs:['post SQL script'],
	skipDuplicateMapInputs: true,
	skipDuplicateMapOutputs: true) ~> AzureDataExplorerSink

如果使用内联数据集，则关联的数据流脚本为：

IncomingStream sink(allowSchemaDrift: true,
    validateSchema: false,
    format: 'table',
    store: 'azuredataexplorer',
    skipDuplicateMapInputs: true,
    skipDuplicateMapOutputs: true) ~> AzureDataExplorerSink

查找活动属性

有关属性的详细信息，请参阅查找活动。

有关复制活动支持作为源和接收器的数据存储的列表，请参阅支持的数据存储。
详细了解如何将数据从 Azure 数据工厂和 Synapse Analytics 复制到 Azure 数据资源管理器。

通过

使用 Azure 数据工厂或 Synapse Analytics 向/从 Azure 数据资源管理器复制数据

支持的功能

入门

使用 UI 创建指向 Azure 数据资源管理器的链接服务

连接器配置详细信息

链接服务属性

服务主体身份验证

系统分配的托管标识身份验证

用户分配的托管标识身份验证

数据集属性

复制活动属性

Azure 数据资源管理器作为源

Azure 数据资源管理器作为接收器

映射数据流属性

源转换

Azure 数据资源管理器源脚本示例

接收器转换

Azure 数据资源管理器接收器脚本示例

查找活动属性

相关内容

其他资源