Azure Data Factory または Synapse Analytics を使用して Azure Data Explorer をコピー先またはコピー元としてデータをコピーする

適用対象: Azure Data Factory Azure Synapse Analytics

この記事では、Azure Data Factory または Synapse Analytics パイプラインでコピー アクティビティを使用して、Azure Data Explorer をコピー先またはコピー元としてデータをコピーする方法について説明します。 この記事は、コピー アクティビティの概要を示しているコピー アクティビティの概要に関する記事に基づいています。

サポートされる機能

この Azure Data Explorer コネクタは、次の機能についてサポートされます。

① Azure 統合ランタイム ② セルフホステッド統合ランタイム

Azure Data Explorer には、サポートされているソース データ ストアからデータをコピーすることができます。 また、Azure Data Explorer のデータを、サポートされているシンク データ ストアにコピーできます。 コピー アクティビティによってソースまたはシンクとしてサポートされているデータ ストアの一覧については、サポートされているデータ ストアに関するページの表をご覧ください。

Azure Data Explorer コネクタを使用すると、次のことができます。

• Microsoft Entra アプリケーション トークン認証とサービス プリンシパルを使用して、データをコピーする。
• ソースとして、KQL (Kusto) クエリを使用してデータを取得する。
• シンクとして、コピー先テーブルにデータを追加する。

作業の開始

パイプラインでコピー アクティビティを実行するには、次のいずれかのツールまたは SDK を使用します。

• データ コピー ツール
• Azure ポータル
• .NET SDK
• Python SDK
• Azure PowerShell
• REST API
• Azure Resource Manager テンプレート

UI を使用して Azure Data Explorer のリンク サービスを作成する

次の手順を使用して、Azure portal UI で Azure Data Explorer のリンク サービスを作成します。

1. Azure Data Factory または Synapse ワークスペースの [管理] タブに移動し、[リンク サービス] を選択して、[新規] をクリックします。

   • Azure Data Factory
   • Azure Synapse

   

2. Explorer を検索し、Azure Data Explorer (Kusto) コネクタを選択します。

   

3. サービスの詳細を構成し、接続をテストして、新しいリンク サービスを作成します。

   

コネクタの構成の詳細

以下のセクションでは、Azure Data Explorer コネクタに固有のエンティティを定義するために使用されるプロパティの詳細を説明します。

リンクされたサービスのプロパティ

Azure Data Explorer コネクタでは、次の認証の種類がサポートされています。 詳細については、対応するセクションをご覧ください。

• サービス プリンシパルの認証
• システム割り当てマネージド ID 認証
• ユーザー割り当てマネージド ID 認証

サービス プリンシパルの認証

サービス プリンシパルの認証を使用するには、次の手順に従ってサービス プリンシパルを取得し、アクセス許可を付与します。

1. Microsoft ID プラットフォームにアプリケーションを登録する。 方法については、「クイック スタート: Microsoft ID プラットフォームにアプリケーションを登録する」を参照してください。 これらの値を記録しておきます。リンクされたサービスを定義するときに使います。

   • アプリケーション ID
   • アプリケーション キー
   • テナント ID

2. Azure Data Explorer でサービス プリンシパルに適切なアクセス許可を付与します。 ロールおよびアクセス許可の詳細について、またアクセス許可の管理方法の詳細については、「Azure Data Explorer のデータベース アクセス許可を管理する」を参照してください。 一般的に、次のことを行う必要があります。

   • ソースとして、少なくともデータベース ビューアー ロールをデータベースに付与します。
   • シンクとして、少なくともデータベース ユーザー ロールをデータベースに付与します。

Azure Data Explorer のリンクされたサービスでは、次のプロパティがサポートされます。

例: サービス プリンシパル キー認証の使用

{
    "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>"
            }
        }
    }
}

システム割り当てマネージド ID 認証

Azure リソース用マネージド ID の詳細については、Azure リソース用マネージド ID に関するページを参照してください。

システム割り当てマネージド ID 認証を使用するには、次の手順に従ってアクセス許可を付与します。

1. ファクトリまたは Synapse ワークスペースと共に生成されたマネージド ID オブジェクト ID の値をコピーして、マネージド ID 情報を取得します。

2. Azure Data Explorer でマネージド ID に適切なアクセス許可を付与します。 ロールおよびアクセス許可の詳細について、またアクセス許可の管理方法の詳細については、「Azure Data Explorer のデータベース アクセス許可を管理する」を参照してください。 一般的に、次のことを行う必要があります。

   • ソースとして、データベース ビューアー ロールをデータベースに付与する。
   • シンクとして、データベース インジェスター ロールおよびデータベース ビューアー ロールをデータベースに付与する。

Azure Data Explorer のリンクされたサービスでは、次のプロパティがサポートされます。

例: システム割り当てマネージド ID 認証を使用する

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

ユーザー割り当てマネージド ID 認証

Azure リソース用マネージド ID の詳細については、Azure リソース用マネージド ID に関するページを参照してください

ユーザー割り当てマネージド ID 認証を使用するには、次の手順に従います。

1. 1 つ以上のユーザー割り当てマネージド ID を作成して、Azure Data Explorer でアクセス許可を付与します。 ロールおよびアクセス許可の詳細について、またアクセス許可の管理方法の詳細については、「Azure Data Explorer のデータベース アクセス許可を管理する」を参照してください。 一般的に、次のことを行う必要があります。

   • ソースとして、少なくともデータベース ビューアー ロールをデータベースに付与します。
   • シンクとして、少なくともデータベースのデータ取り込みロールをデータベースに付与します。

2. 1 つ以上のユーザー割り当てマネージド ID をデータ ファクトリまたは Synapse ワークスペースに割り当て、ユーザー割り当てマネージド ID ごとに資格情報を作成します。

Azure Data Explorer のリンクされたサービスでは、次のプロパティがサポートされます。

例: ユーザー割り当てマネージド ID 認証を使用する

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

データセットのプロパティ

データセットの定義に使用できるセクションとプロパティの一覧については、データセットに関する記事をご覧ください。 このセクションでは、Azure Data Explorer データセットでサポートされるプロパティの一覧を示します。

Azure Data Explorer にデータをコピーするには、データセットの type プロパティを AzureDataExplorerTable に設定します。

次のプロパティがサポートされています。

データセットのプロパティの例:

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

コピー アクティビティのプロパティ

アクティビティの定義に利用できるセクションとプロパティの完全な一覧については、パイプラインとアクティビティに関するページを参照してください。 このセクションでは、Azure Data Explorer のソースとシンクでサポートされるプロパティの一覧を示します。

ソースとしての Azure Data Explorer

Azure Data Explorer からデータをコピーするには、コピー アクティビティ ソースの type プロパティを AzureDataExplorerSource に設定します。 コピー アクティビティの source セクションでは、次のプロパティがサポートされます。

例:

"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 Data Explorer

Azure Data Explorer にデータをコピーするには、コピー アクティビティ シンクの type プロパティを AzureDataExplorerSink に設定します。 コピー アクティビティの sink セクションでは、次のプロパティがサポートされます。

例:

"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"
            }
        ]
    }
]

Mapping Data Flow のプロパティ

マッピング データ フローでデータを変換するときに、Azure Data Explorer のテーブルに対する読み取りと書き込みを実行できます。 詳細については、マッピング データ フローのソース変換とシンク変換に関する記事をご覧ください。 ソースとシンクの種類として、Azure Data Explorer データセットまたはインライン データセットを使用できます。

ソース変換

次の表に、Azure Data Explorer ソースでサポートされるプロパティの一覧を示します。 これらのプロパティは、 [ソース オプション] タブで編集できます。

Azure Data Explorer ソース スクリプトの例

ソースの種類として Azure Data Explorer データセットを使用する場合、関連付けられるデータ フロー スクリプトは次のようになります。

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 Data Explorer シンクでサポートされるプロパティの一覧を示します。 これらのプロパティは、 [設定] タブで編集できます。インライン データセットを使用する場合、「データセットのプロパティ」セクションで説明されているプロパティと同じ追加の設定が表示されます。

Azure Data Explorer シンク スクリプトの例

シンクの種類として Azure Data Explorer データセットを使用する場合、関連付けられているデータ フロー スクリプトは次のようになります。

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

Lookup アクティビティのプロパティ

プロパティの詳細については、ルックアップ アクティビティに関する記事を参照してください。

関連するコンテンツ

• コピー アクティビティでソースおよびシンクとしてサポートされるデータ ストアの一覧については、サポートされるデータ ストアに関するページを参照してください。

• Azure Data Factory と Synapse Analytics から Azure Data Explorer にデータをコピーする方法を参照してください。