共用方式為


使用 Azure Data Factory 或 Synapse Analytics 將資料複製到 Azure 資料總管或從該處複製資料

適用於:Azure Data Factory Azure Synapse Analytics

提示

試用 Microsoft Fabric 中的 Data Factory,這是適用於企業的全方位分析解決方案。 Microsoft Fabric 涵蓋從資料移動到資料科學、即時分析、商業智慧和報告的所有項目。 了解如何免費開始新的試用

本文描述如何使用 Azure Data Factory 和 Synapse Analytics 管線中的複製活動,將資料複製到 Azure 資料總管,或從該處複製資料。 本文係以複製活動概觀一文為基礎,該文提供複製活動的一般概觀。

提示

若要深入了解 Azure 資料總管與服務的整合,請泛讀整合 Azure 資料總管

支援的功能

下列功能支援此 Azure 資料總管連接器:

支援的功能 IR
複製活動 (來源/接收) ① ②
對應資料流 (來源/接收)
查閱活動 ① ②

① Azure 整合執行階段 ② 自我裝載整合執行階段

您可以將資料從任何支援的來源資料存放區複製到 Azure 資料總管。 您也可以將資料從 Azure 資料總管複製到任何支援的接收資料存放區。 如需複製活動支援作為來源或接收器的資料存放區清單,請參閱支援的資料存放區資料表。

注意

3.14 版和更新版本中支援使用自我裝載整合執行階段,透過內部部署資料存放區將資料複製到 Azure 資料總管或從該處複製資料。

使用 Azure 資料總管連接器,您可以執行下列作業:

  • 使用 Microsoft Entra 應用程式權杖驗證搭配服務主體來複製資料。
  • 作為來源時,請使用 KQL (Kusto) 查詢擷取資料。
  • 作為接收時,請將資料附加至目的地資料表。

開始使用

提示

如需 Azure 資料總管連接器的逐步解說,請參閱將資料複製到 Azure 資料總管/從該處複製資料,以及從資料庫大量複製到 Azure 資料總管

若要透過管線執行複製活動,您可以使用下列其中一個工具或 SDK:

使用 UI 建立連結至 Azure 資料總管的服務

使用下列步驟,在 Azure 入口網站 UI 中建立連結至 Azure 資料總管的服務。

  1. 前往 Azure Data Factory 或 Synapse 工作區的 [管理] 索引標籤,選取 [連結服務],然後按一下 [新增]:

  2. 搜尋 [總管],然後選取 [Azure 資料總管 (Kusto) 連接器]。

    Azure 資料總管 (Kusto) 連接器的螢幕擷取畫面。

  3. 設定服務詳細資料,測試連線,然後建立新的連結服務。

    顯示 Azure 資料總管的連結服務設定螢幕擷取畫面。

連接器設定詳細資料

下列各節提供有關屬性的詳細資料,這些屬性會用來定義 Azure 資料總管連接器專屬的實體。

連結服務屬性

Azure 資料總管連接器支援下列驗證類型。 如需詳細資訊,請參閱對應章節:

服務主體驗證

若要使用服務主體驗證,請遵循下列步驟來取得服務主體並授與權限:

  1. 向 Microsoft 身分識別平台註冊應用程式。 若要深入了解,請參閱快速入門:向 Microsoft 身分識別平台註冊應用程式。 請記下這些值,以便用於定義連結服務:

    • Application ID
    • 應用程式金鑰
    • 租用戶識別碼
  2. 在 Azure 資料總管中,將正確的權限授與服務主體。 如需角色和權限以及管理權限的詳細資訊,請參閱管理 Azure 資料總管資料庫權限。 一般而言,您必須:

    • 作為來源,至少將資料庫檢視者角色授與您的資料庫
    • 作為接收器,至少將資料庫使用者角色授與您的資料庫

注意

當您使用 UI 來撰寫時,預設會使用您的登入使用者帳戶來列出 Azure 資料總管叢集、資料庫和資料表。 您可以選擇使用服務主體列出物件,方法是按一下重新整理按鈕旁邊的下拉式清單,或者如果您沒有這些作業的權限,請手動輸入名稱。

Azure 資料總管連結服務支援以下屬性:

屬性 描述 必要
type type 屬性必須設定為 AzureDataExplorer Yes
endpoint Azure 資料總管叢集的端點 URL,格式為 https://<clusterName>.<regionName>.kusto.windows.net Yes
database 資料庫名稱。 Yes
tenant 指定您的應用程式所在租用戶的資訊 (網域名稱或租用戶識別碼)。 這在 Kusto 連接字串中稱為「授權單位識別碼」。 將滑鼠指標暫留在 Azure 入口網站右上角,即可擷取此識別碼。 Yes
servicePrincipalId 指定應用程式的用戶端識別碼。 這在 Kusto 連接字串中稱為「Microsoft Entra 應用程式用戶端識別碼」。 Yes
servicePrincipalKey 指定應用程式的金鑰。 這在 Kusto 連接字串中稱為「Microsoft Entra 應用程式金鑰」。 將此欄位標記為 SecureString 以將其安全地儲存,或參考 Azure Key Vault 中儲存的安全資料 Yes
connectVia 用來連線到資料存放區的整合執行階段。 如果您的資料存放區位於私人網路中,則可使用 Azure Integration Runtime 或自我裝載整合執行階段。 若未指定,則會使用預設 Azure Integration Runtime。 No

範例:使用服務主體金鑰驗證

{
    "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 工作區一起產生的受控識別物件識別碼,藉此擷取受控識別資訊

  2. 在 Azure 資料總管中授與受控識別正確的權限。 如需角色和權限以及管理權限的詳細資訊,請參閱管理 Azure 資料總管資料庫權限。 一般而言,您必須:

    • 作為來源,將資料庫檢視者角色授與您的資料庫。
    • 作為接收器,將資料庫擷取者資料庫檢視者角色授與您的資料庫。

注意

當您使用 UI 來撰寫時,系統會使用您的登入使用者帳戶來列出 Azure 資料總管叢集、資料庫和資料表。 如果您沒有這些作業的權限,請手動輸入名稱。

Azure 資料總管連結服務支援以下屬性:

屬性 描述 必要
type type 屬性必須設定為 AzureDataExplorer Yes
endpoint Azure 資料總管叢集的端點 URL,格式為 https://<clusterName>.<regionName>.kusto.windows.net Yes
database 資料庫名稱。 Yes
connectVia 用來連線到資料存放區的整合執行階段。 如果您的資料存放區位於私人網路中,則可使用 Azure Integration Runtime 或自我裝載整合執行階段。 若未指定,則會使用預設 Azure Integration Runtime。 No

範例:使用系統指派的受控識別驗證

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

使用者指派的受控身分識別驗證

若要深入了解 Azure 資源受控識別,請參閱 Azure 資源受控識別

若要使用使用者指派的受控識別驗證,請依照下列步驟操作:

  1. 在 Azure 資料總管中建立一或多個使用者指派的受控識別,並授與權限。 如需角色和權限以及管理權限的詳細資訊,請參閱管理 Azure 資料總管資料庫權限。 一般而言,您必須:

    • 作為來源,至少將資料庫檢視者角色授與您的資料庫
    • 作為接收器,至少將資料庫擷取者角色授與您的資料庫
  2. 將一或多個使用者指派的受控識別指派給 Data Factory 或 Synapse 工作區,並為每個使用者指派的受控識別建立認證

Azure 資料總管連結服務支援以下屬性:

屬性 描述 必要
type type 屬性必須設定為 AzureDataExplorer Yes
endpoint Azure 資料總管叢集的端點 URL,格式為 https://<clusterName>.<regionName>.kusto.windows.net Yes
database 資料庫名稱。 Yes
credentials 將使用者指派的受控身分識別指定為認證物件。 Yes
connectVia 用來連線到資料存放區的整合執行階段。 如果您的資料存放區位於私人網路中,則可使用 Azure Integration Runtime 或自我裝載整合執行階段。 若未指定,則會使用預設 Azure Integration Runtime。 No

範例:使用使用者指派的受控識別驗證

{
    "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 Yes
table 連結服務所參考的資料表名稱。 Yes (接收):No (來源)

資料集屬性範例:

{
   "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 Yes
query KQL 格式中指定的唯讀要求。 使用自訂的 KQL 查詢作為參考。 Yes
queryTimeout 查詢要求逾時之前的等待時間。預設值是 10 分鐘 (00:10:00);允許的最大值為 1 小時 (01:00:00)。 No
noTruncation 指出是否要截斷傳回的結果集。 根據預設,結果會在 500,000 筆記錄或 64 MB 之後截斷。 強烈建議截斷,以確保活動的正確行為。 No

注意

根據預設,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。 複製活動的 sink 區段支援下列屬性:

屬性 描述 必要
type 複製活動接收器的 type 屬性必須設定為:AzureDataExplorerSink Yes
ingestionMappingName Kusto 資料表上預先建立的對應名稱。 若要將資料行從來源對應至 Azure 資料總管 (適用於所有支援的來源存放區和格式,包括 CSV/JSON/Avro 格式),您可以使用複製活動資料行對應 (隱含方式依名稱或明確方式如設定一般) 和/或 Azure 資料總管。 No
additionalProperties 一種屬性包,其可以用於指定 Azure 資料總管接收器尚未設定的任何擷取屬性。 具體而言,其可以用於指定擷取標籤。 深入了解 Azure 資料總管資料擷取文件 No

範例:

"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 資料庫總管來源所支援的屬性。 您可以在 [來源選項] 索引標籤中編輯這些屬性。

名稱 描述 必要 允許的值 資料流程指令碼屬性
Table 如果您選取 [資料表] 作為輸入,資料流程會在使用內嵌資料集時,從 Azure 資料總管資料集或來源選項中指定的資料表擷取全部資料。 No String (僅限內嵌資料集)
tableName
查詢 KQL 格式中指定的唯讀要求。 使用自訂的 KQL 查詢作為參考。 No String query
Timeout 查詢要求逾時之前的等待時間。預設值為 '172000' (2 天) No 整數 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 資料庫總管接收器所支援的屬性。 您可以在 [設定] 索引標籤中編輯這些屬性。使用內嵌資料集時,您會看到其他設定,其與資料集屬性一節所述的屬性相同。

名稱 描述 必要 允許的值 資料流程指令碼屬性
資料表動作 決定在寫入之前,是否要重新建立或移除目的地資料表中的所有資料列。
- :不會對資料表執行任何動作。
- 重新建立:將會捨棄並重新建立資料表。 如果要動態建立新的資料表,則為必要。
- 截斷:將會移除目標資料表中的所有資料列。
No truefalse recreate
truncate
前置和後置 SQL 指令碼 指定多個 Kusto 控制命令指令碼,這些指令碼將在資料寫入至您的接收器資料庫之前 (前置處理) 和之後 (後置處理) 執行。 No String preSQLs; postSQLs
Timeout 查詢要求逾時之前的等待時間。預設值為 '172000' (2 天) No 整數 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

查閱活動屬性

如需屬性的詳細資訊,請參閱查閱活動