你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn

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

适用于: 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 数据资源管理器的链接服务。

  1. 浏览到 Azure 数据工厂或 Synapse 工作区中的“管理”选项卡并选择“链接服务”,然后单击“新建”:

  2. 搜索资源管理器并选择 Azure 数据资源管理器 (Kusto) 连接器。

    Azure 数据资源管理器 (Kusto) 连接器的屏幕截图。

  3. 配置服务详细信息、测试连接并创建新的链接服务。

    Azure 数据资源管理器的链接服务配置的屏幕截图。

连接器配置详细信息

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

链接服务属性

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

服务主体身份验证

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

  1. 将应用程序注册到 Microsoft 标识平台。 快速入门:通过 Microsoft 标识平台注册应用程序。 记下以下值,这些值用于定义链接服务:

    • 应用程序 ID
    • 应用程序密钥
    • 租户 ID
  2. 在 Azure 数据资源管理器中为服务主体授予正确的权限。 有关角色和权限以及管理权限的详细信息,请参阅管理 Azure 数据资源管理器数据库权限。 一般情况下,必须授予以下权限:

    • 作为源:至少向数据库授予“数据库查看者”角色
    • 作为接收器:至少向数据库授予“数据库用户”角色

注意

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

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

属性 描述 必需
type type 属性必须设置为 AzureDataExplorer
endpoint Azure 数据资源管理器群集的终结点 URL,格式为 https://<clusterName>.<regionName>.kusto.windows.net
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.windows.net ",
            "database": "<database name>",
            "tenant": "<tenant name/id e.g. microsoft.onmicrosoft.com>",
            "servicePrincipalId": "<service principal id>",
            "servicePrincipalKey": {
                "type": "SecureString",
                "value": "<service principal key>"
            }
        }
    }
}

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

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

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

  1. 通过复制与工厂或 Synapse 工作区一起生成的“托管标识对象 ID”值,检索托管标识信息

  2. 在 Azure 数据资源管理器中向托管标识授予正确的权限。 有关角色和权限以及管理权限的详细信息,请参阅管理 Azure 数据资源管理器数据库权限。 一般情况下,必须授予以下权限:

    • 作为源:授予对数据库的“数据库查看者”角色
    • 作为接收器:授予对数据库的“数据库引入者”和“数据库查看者”角色。

注意

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

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

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

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

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

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

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

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

  1. 创建一个或多个用户分配的托管标识,并在 Azure 数据资源管理器中授予权限。 有关角色和权限以及管理权限的详细信息,请参阅管理 Azure 数据资源管理器数据库权限。 一般情况下,必须授予以下权限:

    • 作为源:至少向数据库授予“数据库查看者”角色
    • 作为接收器:至少向数据库授予“数据库引入者”角色
  2. 为数据工厂或 Synapse 工作区分配一个或多个用户分配的托管标识,并为每个用户分配的托管标识创建凭据

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

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

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

{
    "name": "AzureDataExplorerLinkedService",
    "properties": {
        "type": "AzureDataExplorer",
        "typeProperties": {
            "endpoint": "https://<clusterName>.<regionName>.kusto.windows.net ",
            "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 数据资源管理器接收器支持的属性。 可以在“设置”选项卡中编辑这些属性。使用内联数据集时,你会看到其他设置,这些设置与数据集属性部分描述的属性相同。

名称 说明 必需 允许的值 数据流脚本属性
表操作 确定在写入之前是否从目标表重新创建或删除所有行。
- :不会对表进行任何操作。
- 重新创建:将删除表并重新创建表。 如果以动态方式创建表,则是必需的。
- 截断:将删除目标表中的所有行。
truefalse 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

查找活动属性

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