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

[アーティクル]
05/15/2024

適用対象: Azure Data Factory Azure Synapse Analytics

ヒント

企業向けのオールインワン分析ソリューション、Microsoft Fabric の Data Factory をお試しください。 Microsoft Fabric は、データ移動からデータサイエンス、リアルタイム分析、ビジネスインテリジェンス、レポートまで、あらゆるものをカバーしています。無料で新しい試用版を開始する方法について説明します。

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

ヒント

Azure Data Explorer のサービスとの統合の詳細については、「Azure Data Explorer の統合」を参照してください。

サポートされる機能

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

サポートされる機能	IR
Copy アクティビティ (ソース/シンク)	① ②
マッピングデータフロー (ソース/シンク)	①
Lookup アクティビティ	① ②

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

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

注意

セルフホステッド統合ランタイムを使用して、Azure Data Explorer との間でオンプレミスデータストアから双方向にデータをコピーすることは、バージョン 3.14 以降からサポートされています。

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

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

作業の開始

ヒント

Azure Data Explorer コネクタのチュートリアルについては、「Azure Data Explorer との間でデータをコピーする」と、データベースから Azure Data Explorer への一括コピーに関するページを参照してください。

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

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

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

Azure Data Factory または Synapse ワークスペースの [管理] タブに移動し、[リンクサービス] を選択して、[新規] をクリックします。
- Azure Data Factory
- Azure Synapse
Explorer を検索し、Azure Data Explorer (Kusto) コネクタを選択します。
サービスの詳細を構成し、接続をテストして、新しいリンクサービスを作成します。

コネクタの構成の詳細

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

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

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

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

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

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

Microsoft ID プラットフォームにアプリケーションを登録する。方法については、「クイックスタート: Microsoft ID プラットフォームにアプリケーションを登録する」を参照してください。これらの値を記録しておきます。リンクされたサービスを定義するときに使います。
- アプリケーション ID
- アプリケーションキー
- テナント ID
Azure Data Explorer でサービスプリンシパルに適切なアクセス許可を付与します。ロールおよびアクセス許可の詳細について、またアクセス許可の管理方法の詳細については、「Azure Data Explorer のデータベースアクセス許可を管理する」を参照してください。一般的に、次のことを行う必要があります。
- ソースとして、少なくともデータベースビューアー ロールをデータベースに付与します。
- シンクとして、少なくともデータベースユーザー ロールをデータベースに付与します。

注意

UI を使用して作成する場合、既定では、Azure Data Explorer クラスター、データベース、およびテーブルを一覧表示するために、ログインユーザーアカウントが使用されます。サービスプリンシパルを使用してオブジェクトを一覧表示するには、更新ボタンの横にあるドロップダウンをクリックします。これらの操作に対するアクセス許可がない場合は、名前を手動で入力します。

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

プロパティ	内容	必須
type	type プロパティは、AzureDataExplorer に設定する必要があります。	はい
endpoint	Azure Data Explorer クラスターのエンドポイント URL。形式は `https://<clusterName>.<regionName>.kusto.windows.net` です。	はい
database	データベースの名前。	はい
tenant	アプリケーションが存在するテナントの情報 (ドメイン名またはテナント ID) を指定します。これは、Kusto 接続文字列の "機関 ID" として知られています。これは、Azure portal の右上隅にマウスポインターを合わせることで取得できます。	はい
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>"
            }
        }
    }
}

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

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

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

ファクトリまたは Synapse ワークスペースと共に生成されたマネージド ID オブジェクト ID の値をコピーして、マネージド ID 情報を取得します。
Azure Data Explorer でマネージド ID に適切なアクセス許可を付与します。ロールおよびアクセス許可の詳細について、またアクセス許可の管理方法の詳細については、「Azure Data Explorer のデータベースアクセス許可を管理する」を参照してください。一般的に、次のことを行う必要があります。
- ソースとして、データベースビューアー ロールをデータベースに付与する。
- シンクとして、データベースインジェスター ロールおよびデータベースビューアー ロールをデータベースに付与する。

Note

UI を使用して作成する場合、Azure Data Explorer クラスター、データベース、およびテーブルを一覧表示するために、ログインユーザーアカウントが使用されます。これらの操作のためのアクセス許可がない場合は、名前を手動で入力します。

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

プロパティ	内容	必須
type	type プロパティは、AzureDataExplorer に設定する必要があります。	はい
endpoint	Azure Data Explorer クラスターのエンドポイント URL。形式は `https://<clusterName>.<regionName>.kusto.windows.net` です。	はい
database	データベースの名前。	はい
connectVia	データストアに接続するために使用される統合ランタイム。データストアがプライベートネットワーク内にある場合、Azure Integration Runtime またはセルフホステッド統合ランタイムを使用できます。指定されていない場合は、既定の Azure Integration Runtime が使用されます。	いいえ

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

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

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

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

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

1 つ以上のユーザー割り当てマネージド ID を作成して、Azure Data Explorer でアクセス許可を付与します。ロールおよびアクセス許可の詳細について、またアクセス許可の管理方法の詳細については、「Azure Data Explorer のデータベースアクセス許可を管理する」を参照してください。一般的に、次のことを行う必要があります。
- ソースとして、少なくともデータベースビューアー ロールをデータベースに付与します。
- シンクとして、少なくともデータベースのデータ取り込みロールをデータベースに付与します。
1 つ以上のユーザー割り当てマネージド ID をデータファクトリまたは Synapse ワークスペースに割り当て、ユーザー割り当てマネージド ID ごとに資格情報を作成します。

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

プロパティ	内容	必須
type	type プロパティは、AzureDataExplorer に設定する必要があります。	はい
endpoint	Azure Data Explorer クラスターのエンドポイント URL。形式は `https://<clusterName>.<regionName>.kusto.windows.net` です。	はい
database	データベースの名前。	はい
資格情報	ユーザー割り当てマネージド ID を資格情報オブジェクトとして指定します。	はい
connectVia	データストアに接続するために使用される統合ランタイム。データストアがプライベートネットワーク内にある場合、Azure Integration Runtime またはセルフホステッド統合ランタイムを使用できます。指定されていない場合は、既定の Azure Integration Runtime が使用されます。	いいえ

例: ユーザー割り当てマネージド 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 に設定します。

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

プロパティ	内容	必須
type	type プロパティは、AzureDataExplorerTable に設定する必要があります。	はい
table	リンクされたサービスが参照するテーブルの名前。	シンクの場合は Yes、ソースの場合は No

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

{
   "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 セクションでは、次のプロパティがサポートされます。

プロパティ	内容	必須
type	コピーアクティビティのソースの type プロパティを、次の値に設定する必要があります:AzureDataExplorerSource	はい
query	KQL 形式で指定された読み取り専用要求。参照としてカスタム KQL クエリを使用します。	はい
queryTimeout	クエリ要求がタイムアウトするまでの待機時間。既定値は 10 分 (00:10:00)、許容される最大値は 1 時間 (01:00:00) です。	いいえ
noTruncation	返される結果セットを切り詰めるかどうかを示します。既定では、結果は 500,000 件のレコードまたは 64 メガバイト (MB) の後に切り詰められます。アクティビティの正常な動作のためには、切り詰めを強くお勧めします。	いいえ

注意

既定では、Azure Data Explorer ソースには、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 Data Explorer

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

プロパティ	内容	必須
type	コピーアクティビティのシンクの type プロパティは、次のように設定する必要があります:AzureDataExplorerSink	はい
ingestionMappingName	Kusto テーブルで事前作成済みのマッピングの名前。ソースから Azure Data Explorer に列をマッピングするには (CSV/JSON/Avro 形式など、サポートされているすべてのソースストアや形式に適用されます)、コピーアクティビティの列マッピング (名前で暗黙的に、または構成で明示的に) や Azure Data Explorer のマッピングを使用できます。	いいえ
additionalProperties	まだ Azure Data Explorer シンクによって設定されていないインジェストのプロパティを指定するために使用できるプロパティバッグ。具体的には、インジェストタグの指定に便利です。詳細については Azure Data Explore データインジェストドキュメントでご覧ください。	いいえ

例:

"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 データセットで指定された、またはインラインデータセットを使用するときにソースオプションで指定されたテーブルからすべてのデータがフェッチされます。	いいえ	String	(インラインデータセットのみ) tableName
クエリ	KQL 形式で指定された読み取り専用要求。参照としてカスタム KQL クエリを使用します。	いいえ	String	query
タイムアウト	クエリ要求がタイムアウトするまでの待機時間。既定値は '172000' (2 日間) です。	いいえ	Integer	timeout

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

名前	説明	必須	使用できる値	データフロースクリプトのプロパティ
テーブルアクション	書き込み前に変換先テーブルのすべての行を再作成するか削除するかを指定します。 - なし: テーブルに対してアクションは実行されません。 - Recreate:テーブルが削除され、再作成されます。新しいテーブルを動的に作成する場合に必要です。 - Truncate:ターゲットテーブルのすべての行が削除されます。	いいえ	`true` または `false`	recreate truncate
事前および事後の SQL スクリプト	データがシンクデータベースに書き込まれる前 (前処理) と書き込まれた後 (後処理) に実行される複数の Kusto 管理コマンドを指定します。	いいえ	String	preSQL; postSQL
タイムアウト	クエリ要求がタイムアウトするまでの待機時間。既定値は '172000' (2 日間) です。	いいえ	Integer	timeout

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 にデータをコピーする方法を参照してください。

次の方法で共有

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

サポートされる機能

作業の開始

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

コネクタの構成の詳細

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

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

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

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

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

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

ソースとしての Azure Data Explorer

シンクとしての Azure Data Explorer

Mapping Data Flow のプロパティ

ソース変換

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

シンク変換

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

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

フィードバック

その他のリソース

次の方法で共有

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

サポートされる機能

作業の開始

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

コネクタの構成の詳細

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

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

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

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

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

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

ソースとしての Azure Data Explorer

シンクとしての Azure Data Explorer

Mapping Data Flow のプロパティ

ソース変換

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

シンク変換

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

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

関連するコンテンツ

フィードバック

その他のリソース

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

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

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

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

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