Azure Data Factory や Synapse パイプラインを使用して Azure Synapse Analytics のデータをコピー、変換する

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

適用対象: Azure Data Factory Azure Synapse Analytics

ヒント

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

この記事では、Azure Data Factory や Synapse パイプラインのコピーアクティビティを使用して、Azure Synapse Analytics との間でデータをコピーし、Data Flow を使用して Azure Data Lake Storage Gen2 のデータを変換する方法について説明します。 Azure Data Factory については、入門記事でをご覧ください。

サポートされる機能

この Azure Synapse Analytics コネクタは、次の機能でサポートされています。

サポートされる機能	IR	マネージドプライベートエンドポイント
Copy アクティビティ (ソース/シンク)	① ②	✓
マッピングデータフロー (ソース/シンク)	①	✓
Lookup アクティビティ	① ②	✓
GetMetadata アクティビティ	① ②	✓
スクリプト活動	① ②	✓
ストアドプロシージャアクティビティ	① ②	✓

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

コピーアクティビティについて、この Azure Synapse Analytics コネクタでは次の機能がサポートされます。

SQL 認証および Microsoft Entra アプリケーショントークン認証と、Azure リソースのサービスプリンシパルまたはマネージド ID を使って、データをコピーする。
ソースとして、SQL クエリまたはストアドプロシージャを使用してデータを取得する。 Azure Synapse Analytics ソースから並列コピーを行うこともできます。詳細については、「Azure Synapse Analytics からの並列コピー」セクションを参照してください。
シンクとして、COPY ステートメントまたは PolyBase、あるいは一括挿入を使用してデータを読み込みます。コピーのパフォーマンスを向上させるために、COPY ステートメントまたは PolyBase をお勧めします。また、ソーススキーマに基づいて、DISTRIBUTION = ROUND_ROBIN の宛先テーブルが存在しない場合、自動的に作成することもできます。

重要

Azure Integration Runtime を使ってデータをコピーする場合は、Azure サービスが論理 SQL サーバーにアクセスできるようにサーバーレベルのファイアウォール規則を構成します。セルフホステッド統合ランタイムを使用してデータをコピーする場合は、適切な IP 範囲を許可するようにファイアウォールを構成します。この範囲には、Azure Synapse Analytics への接続に使用されるマシンの IP が含まれています。

はじめに

ヒント

最高のパフォーマンスを実現するには、PolyBase または COPY ステートメントを使用して、Azure Synapse Analytics にデータを読み込みます。詳細については、「PolyBase を使用して Azure Synapse Analytics にデータを読み込む」および COPY ステートメントを使用して Azure Synapse Analytics にデータを読み込む方法に関するセクションを参照してください。ユースケースを使用したチュートリアルについては、Azure Data Factory を使用して 1 TB のデータを 15 分以内に Azure Synapse Analytics に読み込む方法に関する記事をご覧ください。

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

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

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

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

コネクタの構成の詳細

以下のセクションでは、Azure Synapse Analytics コネクタに固有の Data Factory と Synapse パイプラインエンティティを定義するプロパティについて詳しく説明します。

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

Azure Synapse Analytics のリンクサービスでは、こちらの汎用プロパティがサポートされています。

プロパティ	内容	必須
type	type プロパティは AzureSqlDW に設定する必要があります。	はい
connectionString	connectionString プロパティには、Azure Synapse Analytics インスタンスに接続するために必要な情報を指定します。安全に格納するには、このフィールドを SecureString とマークします。パスワード/サービスプリンシパルキーを Azure Key Vault に格納して、それが SQL 認証の場合は接続文字列から `password` 構成をプルすることもできます。詳しくは、表の下の JSON の例と、「Azure Key Vault への資格情報の格納」の記事をご覧ください。	はい
azureCloudType	サービスプリンシパル認証の場合に、Microsoft Entra アプリケーションが登録されている Azure クラウド環境の種類を指定します。使用できる値は、`AzurePublic`、`AzureChina`、`AzureUsGovernment`、`AzureGermany` です。既定では、データファクトリまたは Synapse パイプラインのクラウド環境が使用されます。	いいえ
connectVia	データストアに接続するために使用される統合ランタイム。 Azure Integration Runtime またはセルフホステッド統合ランタイムを使用できます (データストアがプライベートネットワークにある場合)。指定されていない場合は、既定の Azure 統合ランタイムが使用されます。	いいえ

さまざまな認証の種類に対する固有のプロパティ、前提条件、および JSON サンプルについては、以降のセクションをご覧ください。

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

ヒント

Azure portal から Azure Synapse にサーバーレス SQL プール用のリンクされたサービスを作成する場合:

[アカウントの選択方法] については、[手動で入力] を選択します
サーバーレスエンドポイントの完全修飾ドメイン名を貼り付けます。これは、ご使用の Synapse ワークスペースの Azure portal 概要ページの [Serverless SQL endpoint] (サーバーレス SQL エンドポイント) のプロパティにあります。たとえば、「 myserver-ondemand.sql-azuresynapse.net 」のように入力します。
[データベース名] に、サーバーレス SQL プールのデータベース名を指定します。

ヒント

エラーコード "UserErrorFailedToConnectToSqlServer" および "The session limit for the database is XXX and has been reached." (データベースのセッション制限 XXX に達しました) のようなメッセージのエラーが発生する場合は、Pooling=false を接続文字列に追加して、もう一度試してください。

SQL 認証

SQL 認証の種類を使用するには、前のセクションで説明した汎用プロパティを指定します。

SQL 認証を使用するリンクされたサービスの例

{
    "name": "AzureSqlDWLinkedService",
    "properties": {
        "type": "AzureSqlDW",
        "typeProperties": {
            "connectionString": "Server=tcp:<servername>.database.windows.net,1433;Database=<databasename>;User ID=<username>@<servername>;Password=<password>;Trusted_Connection=False;Encrypt=True;Connection Timeout=30"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Azure Key Vault 内のパスワード:

{
    "name": "AzureSqlDWLinkedService",
    "properties": {
        "type": "AzureSqlDW",
        "typeProperties": {
            "connectionString": "Server=tcp:<servername>.database.windows.net,1433;Database=<databasename>;User ID=<username>@<servername>;Trusted_Connection=False;Encrypt=True;Connection Timeout=30",
            "password": {
                "type": "AzureKeyVaultSecret",
                "store": {
                    "referenceName": "<Azure Key Vault linked service name>",
                    "type": "LinkedServiceReference"
                },
                "secretName": "<secretName>"
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

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

前のセクションで説明した汎用的なプロパティに加えて、サービスプリンシパルの認証を使用するには、次のプロパティを指定します。

プロパティ	内容	必須
servicePrincipalId	アプリケーションのクライアント ID を取得します。	はい
servicePrincipalKey	アプリケーションのキーを取得します。このフィールドを SecureString とマークして安全に保存するか、Azure Key Vault に保存されているシークレットを参照します。	はい
tenant	アプリケーションが存在するテナントの情報 (ドメイン名またはテナント ID) を指定します。 Azure Portal の右上隅にマウスを置くことで取得できます。	はい

以下の手順に従う必要もあります。

Azure portal から Microsoft Entra アプリケーションを作成します。アプリケーション名と、リンクされたサービスを定義する次の値を記録しておきます。
- アプリケーション ID
- アプリケーションキー
- テナント ID
まだ行っていない場合は、Azure portal でサーバーの Microsoft Entra 管理者をプロビジョニングします。 Microsoft Entra ユーザーまたは Microsoft Entra グループを、Microsoft Entra 管理者にすることができます。マネージド ID を持つグループに管理者ロールを付与する場合は、ステップ 3 と 4 をスキップします。管理者は、データベースへのフルアクセスを持ちます。
サービスプリンシパルの 包含データベースユーザーを作成します 。 SSMS のようなツールと、少なくとも ALTER ANY USER アクセス許可を持つ Microsoft Entra の ID を使って、データをコピーするデータウェアハウスに接続します。次の T-SQL を実行します。
```
CREATE USER [your_application_name] FROM EXTERNAL PROVIDER;
```
SQL ユーザーや他のユーザーに対する通常の方法で、サービスプリンシパルに必要なアクセス許可を付与します。次のコードを実行するか、こちらでその他のオプションを参照してください。 PolyBase を使用してデータを読み込む場合は、必要なデータベースアクセス許可について学習します。
```
EXEC sp_addrolemember db_owner, [your application name];
```
Azure Data Factory や Synapse ワークスペースで、Azure Synapse Analytics のリンクされたサービスを構成します。

サービスプリンシパル認証を使うリンクされたサービスの例

{
    "name": "AzureSqlDWLinkedService",
    "properties": {
        "type": "AzureSqlDW",
        "typeProperties": {
            "connectionString": "Server=tcp:<servername>.database.windows.net,1433;Database=<databasename>;Connection Timeout=30",
            "servicePrincipalId": "<service principal id>",
            "servicePrincipalKey": {
                "type": "SecureString",
                "value": "<service principal key>"
            },
            "tenant": "<tenant info, e.g. microsoft.onmicrosoft.com>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Azure リソース認証用のシステム割り当てマネージド ID

データファクトリや Synapse ワークスペースは、リソースを表す Azure リソース用のシステム割り当てマネージド ID と関連付けることができます。このマネージド ID を Azure Synapse Analytics の認証に使用できます。指定されたリソースは、この ID を使用してデータウェアハウスにアクセスし、データを双方向にコピーできます。

システム割り当てマネージド ID 認証を使用するには、前のセクションで説明した汎用プロパティを指定し、次の手順に従います。

まだ行っていない場合は、Azure portal でサーバーの Microsoft Entra 管理者をプロビジョニングします。 Microsoft Entra ユーザーまたは Microsoft Entra グループを、Microsoft Entra 管理者にすることができます。システム割り当てマネージド ID を持つグループに管理者ロールを付与する場合は、ステップ 3 および 4 をスキップします。管理者は、データベースへのフルアクセスを持ちます。
システム割り当てマネージド ID の包含データベースユーザーを作成します。 SSMS のようなツールと、少なくとも ALTER ANY USER アクセス許可を持つ Microsoft Entra の ID を使って、データをコピーするデータウェアハウスに接続します。次の T-SQL を実行します。
```
CREATE USER [your_resource_name] FROM EXTERNAL PROVIDER;
```
通常の SQL ユーザーなどと同様に、システム割り当てマネージド ID に必要なアクセス許可を付与します。次のコードを実行するか、こちらでその他のオプションを参照してください。 PolyBase を使用してデータを読み込む場合は、必要なデータベースアクセス許可について学習します。
```
EXEC sp_addrolemember db_owner, [your_resource_name];
```
Azure Synapse Analytics のリンクされたサービスを作成する。

例:

{
    "name": "AzureSqlDWLinkedService",
    "properties": {
        "type": "AzureSqlDW",
        "typeProperties": {
            "connectionString": "Server=tcp:<servername>.database.windows.net,1433;Database=<databasename>;Connection Timeout=30"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

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

データファクトリや Synapse ワークスペースは、リソースを表すユーザー割り当てマネージド ID と関連付けることができます。このマネージド ID を Azure Synapse Analytics の認証に使用できます。指定されたリソースは、この ID を使用してデータウェアハウスにアクセスし、データを双方向にコピーできます。

前のセクションで説明した汎用的なプロパティに加えて、ユーザー割り当てマネージド ID 認証を使用するには、次のプロパティを指定します。

プロパティ	内容	必須
資格情報	ユーザー割り当てマネージド ID を資格情報オブジェクトとして指定します。	はい

以下の手順に従う必要もあります。

まだ行っていない場合は、Azure portal でサーバーの Microsoft Entra 管理者をプロビジョニングします。 Microsoft Entra ユーザーまたは Microsoft Entra グループを、Microsoft Entra 管理者にすることができます。ユーザー割り当てマネージド ID を持つグループに管理者ロールを付与する場合は、ステップ 3 をスキップします。管理者は、データベースへのフルアクセスを持ちます。
ユーザー割り当てマネージド ID の包含データベースユーザーを作成します。 SSMS のようなツールと、少なくとも ALTER ANY USER アクセス許可を持つ Microsoft Entra の ID を使って、データをコピーするデータウェアハウスに接続します。次の T-SQL を実行します。
```
CREATE USER [your_resource_name] FROM EXTERNAL PROVIDER;
```
1 つ以上のユーザー割り当てマネージド ID を作成し、通常の SQL ユーザーなどと同様に、ユーザー割り当てマネージド ID に必要なアクセス許可を付与します。次のコードを実行するか、こちらでその他のオプションを参照してください。 PolyBase を使用してデータを読み込む場合は、必要なデータベースアクセス許可について学習します。
```
EXEC sp_addrolemember db_owner, [your_resource_name];
```
1 つ以上のユーザー割り当てマネージド ID をデータファクトリに割り当てて、ユーザー割り当てマネージド ID ごとに資格情報を作成します。
Azure Synapse Analytics のリンクされたサービスを作成する。

例:

{
    "name": "AzureSqlDWLinkedService",
    "properties": {
        "type": "AzureSqlDW",
        "typeProperties": {
            "connectionString": "Server=tcp:<servername>.database.windows.net,1433;Database=<databasename>;Connection Timeout=30",
            "credential": {
                "referenceName": "credential1",
                "type": "CredentialReference"
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

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

データセットを定義するために使用できるセクションとプロパティの完全な一覧については、データセットに関する記事をご覧ください。

Azure Synapse Analytics データセットでは、次のプロパティがサポートされています。

プロパティ	内容	必須
type	データセットの type プロパティは、AzureSqlDWTable を設定する必要があります。	はい
schema	スキーマの名前。	ソースの場合はいいえ、シンクの場合ははい
table	テーブル/ビューの名前。	ソースの場合はいいえ、シンクの場合ははい
tableName	スキーマがあるテーブル/ビューの名前。このプロパティは下位互換性のためにサポートされています。新しいワークロードでは、`schema` と `table` を使用します。	ソースの場合はいいえ、シンクの場合ははい

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

{
    "name": "AzureSQLDWDataset",
    "properties":
    {
        "type": "AzureSqlDWTable",
        "linkedServiceName": {
            "referenceName": "<Azure Synapse Analytics linked service name>",
            "type": "LinkedServiceReference"
        },
        "schema": [ < physical schema, optional, retrievable during authoring > ],
        "typeProperties": {
            "schema": "<schema_name>",
            "table": "<table_name>"
        }
    }
}

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

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

ソースとしての Azure Synapse Analytics

ヒント

データパーティション分割を使用して Azure Synapse Analytics からデータを効率的に読み込む方法の詳細については、「Azure Synapse Analytics からの並列コピー」を参照してください。

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

プロパティ	内容	必須
type	コピーアクティビティのソースの type プロパティは SqlDWSource に設定する必要があります。	はい
sqlReaderQuery	カスタム SQL クエリを使用してデータを読み取ります。例: `select * from MyTable`.	いいえ
sqlReaderStoredProcedureName	ソーステーブルからデータを読み取るストアドプロシージャの名前。最後の SQL ステートメントはストアドプロシージャの SELECT ステートメントにする必要があります。	いいえ
storedProcedureParameters	ストアドプロシージャのパラメーター。使用可能な値は、名前または値のペアです。パラメーターの名前とその大文字と小文字は、ストアドプロシージャのパラメーターの名前とその大文字小文字と一致する必要があります。	いいえ
isolationLevel	SQL ソースのトランザクションロック動作を指定します。使用できる値は、次のとおりです。ReadCommitted、ReadUncommitted、RepeatableRead、Serializable、Snapshot。指定しなかった場合は、データベースの既定の分離レベルが使用されます。詳細については、「system.data.isolationlevel」を参照してください。	いいえ
partitionOptions	Azure Synapse Analytics からのデータの読み込みに使用されるデータパーティション分割オプションを指定します。使用できる値は、以下のとおりです。None (既定値)、PhysicalPartitionsOfTable、および DynamicRange。パーティションオプションが有効になっている場合 (つまり、`None` ではない場合)、Azure Synapse Analytics から同時にデータを読み込む並列度は、コピーアクティビティの `parallelCopies` の設定によって制御されます。	いいえ
partitionSettings	データパーティション分割の設定のグループを指定します。パーティションオプションが `None` でない場合に適用されます。	いいえ
`partitionSettings` の下:
partitionColumnName	並列コピーの範囲パーティション分割で使用される整数型または日付/日時型 (`int`、`smallint`、`bigint`、`date`、`smalldatetime`、`datetime`、`datetime2`、または `datetimeoffset`) のソース列の名前を指定します。指定しない場合は、テーブルのインデックスまたは主キーが自動的に検出され、パーティション列として使用されます。パーティションオプションが `DynamicRange` である場合に適用されます。クエリを使用してソースデータを取得する場合は、WHERE 句で `?DfDynamicRangePartitionCondition` をフックします。例については、「SQL データベースからの並列コピー」セクションを参照してください。	いいえ
partitionUpperBound	パーティション範囲の分割のための、パーティション列の最大値。この値は、テーブル内の行のフィルター処理用ではなく、パーティションのストライドを決定するために使用されます。テーブルまたはクエリ結果に含まれるすべての行がパーティション分割され、コピーされます。指定されていない場合は、コピーアクティビティによって値が自動検出されます。パーティションオプションが `DynamicRange` である場合に適用されます。例については、「SQL データベースからの並列コピー」セクションを参照してください。	いいえ
partitionLowerBound	パーティション範囲の分割のための、パーティション列の最小値。この値は、テーブル内の行のフィルター処理用ではなく、パーティションのストライドを決定するために使用されます。テーブルまたはクエリ結果に含まれるすべての行がパーティション分割され、コピーされます。指定されていない場合は、コピーアクティビティによって値が自動検出されます。パーティションオプションが `DynamicRange` である場合に適用されます。例については、「SQL データベースからの並列コピー」セクションを参照してください。	いいえ

以下の点に注意してください。

ソースのストアドプロシージャを使用してデータを取得する場合、異なるパラメーター値が渡されたときにストアドプロシージャが別のスキーマを返すように設計されていると、UI からスキーマをインポートするとき、または自動テーブル作成を使用して SQL データベースにデータをコピーするときに、エラーが発生したり、予期しない結果が表示されます。

例: SQL クエリの使用

"activities":[
    {
        "name": "CopyFromAzureSQLDW",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<Azure Synapse Analytics input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "SqlDWSource",
                "sqlReaderQuery": "SELECT * FROM MyTable"
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

例: ストアドプロシージャの使用

"activities":[
    {
        "name": "CopyFromAzureSQLDW",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<Azure Synapse Analytics input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "SqlDWSource",
                "sqlReaderStoredProcedureName": "CopyTestSrcStoredProcedureWithParameters",
                "storedProcedureParameters": {
                    "stringData": { "value": "str3" },
                    "identifier": { "value": "$$Text.Format('{0:yyyy}', <datetime parameter>)", "type": "Int"}
                }
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

サンプルストアドプロシージャ:

CREATE PROCEDURE CopyTestSrcStoredProcedureWithParameters
(
    @stringData varchar(20),
    @identifier int
)
AS
SET NOCOUNT ON;
BEGIN
    select *
    from dbo.UnitTestSrcTable
    where dbo.UnitTestSrcTable.stringData != stringData
    and dbo.UnitTestSrcTable.identifier != identifier
END
GO

シンクとしての Azure Synapse Analytics

Azure Data Factory と Synapse パイプラインでは、Azure Synapse Analytics にデータを読み込む 3 つの方法がサポートされています。

COPY ステートメントを使用する
PolyBase を使用する
一括挿入を使用する

データを読み込む最も高速でスケーラブルな方法は、COPY ステートメントまたは PolyBase を使用することです。

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

プロパティ	内容	必須
type	コピーアクティビティのシンクの type プロパティは、SqlDWSink に設定する必要があります。	はい
allowPolyBase	PolyBase を使用して Azure Synapse Analytics にデータを読み込むかどうかを示します。 `allowCopyCommand` と `allowPolyBase` の両方を true に設定することはできません。制約と詳細については、「PolyBase を使用して Azure Synapse Analytics にデータを読み込む」をご覧ください。使用可能な値: True、および False (既定値)。	いいえ。 PolyBase を使用する場合に適用します。
polyBaseSettings	`allowPolybase` プロパティが true に設定されているときに指定できるプロパティのグループ。	いいえ。 PolyBase を使用する場合に適用します。
allowCopyCommand	Azure Synapse Analytics にデータを読み込む際に、COPY ステートメントを使用するかどうかを示します。 `allowCopyCommand` と `allowPolyBase` の両方を true に設定することはできません。制約と詳細については、「COPY ステートメントを使用して Azure Synapse Analytics にデータを読み込む」をご覧ください。使用可能な値: True、および False (既定値)。	いいえ。 COPY を使用する場合に適用します。
copyCommandSettings	`allowCopyCommand` プロパティが TRUE に設定されているときに指定できるプロパティのグループ。	いいえ。 COPY を使用する場合に適用します。
writeBatchSize	SQL テーブルに挿入するバッチあたりの行数。使用可能な値は integer (行数) です。既定では行のサイズに基づいて、サービスにより適切なバッチサイズが動的に決定されます。	いいえ。一括挿入を使用する場合に適用します。
writeBatchTimeout	タイムアウトする前に挿入、アップサート、およびストアドプロシージャ操作が完了するまでの待機時間です。使用可能な値は期間に対する値です。たとえば "00:30:00" (30 分) を指定できます。値を指定しなかった場合、タイムアウトの既定値は "00:30:00" です。	いいえ。一括挿入を使用する場合に適用します。
preCopyScript	コピーアクティビティの毎回の実行で、データを Azure Synapse Analytics に書き込む前に実行する SQL クエリを指定します。前に読み込まれたデータをクリーンアップするには、このプロパティを使います。	いいえ
tableOption	シンクテーブルが存在しない場合に、ソースのスキーマに基づいて、シンクテーブルを自動的に作成するかどうかを指定します。使用できる値は `none` (既定値)、`autoCreate` です。	いいえ
disableMetricsCollection	サービスでは、コピーのパフォーマンスの最適化と推奨を目的として、Azure Synapse Analytics DWU などのメトリックが収集されます。これにより、マスター DB への追加アクセスが発生します。この動作に不安がある場合は、`true` を指定してオフにします。	いいえ (既定値は `false`)
maxConcurrentConnections	アクティビティの実行中にデータストアに対して確立されたコンカレント接続数の上限。コンカレント接続を制限する場合にのみ、値を指定します。	なし
WriteBehavior	Azure SQL Database にデータを読み込むコピーアクティビティの書き込み動作を指定します。使用できる値は、Insert と Upsert です。既定では、サービスは Insert を使用してデータを読み込みます。	いいえ
upsertSettings	書き込み動作の設定のグループを指定します。 WriteBehavior オプションが `Upsert` である場合に適用します。	いいえ
`upsertSettings` の下:
キー	行を一意に識別するための列名を指定します。 1 つのキーまたは一連のキーのいずれかを使用できます。指定しない場合は、主キーが使用されます。	いいえ
interimSchemaName	中間テーブルを作成するために中間スキーマを指定します。注: ユーザーは、テーブルの作成と削除を行うアクセス許可を持っている必要があります。既定では、中間テーブルはシンクテーブルと同じスキーマを共有します。	いいえ

例 1: Azure Synapse Analytics シンク

"sink": {
    "type": "SqlDWSink",
    "allowPolyBase": true,
    "polyBaseSettings":
    {
        "rejectType": "percentage",
        "rejectValue": 10.0,
        "rejectSampleValue": 100,
        "useTypeDefault": true
    }
}

例 2: データをアップサートする

"sink": {
    "type": "SqlDWSink",
    "writeBehavior": "Upsert",
    "upsertSettings": {
        "keys": [
             "<column name>"
        ],
        "interimSchemaName": "<interim schema name>"
    },
}

Azure Synapse Analytics からの並列コピー

Azure Synapse Analytics コネクタでは、コピーアクティビティの際に、データを並列でコピーするための組み込みのデータパーティション分割が提供されます。データパーティション分割オプションは、コピーアクティビティの [ソース] タブにあります。

パーティションのオプションのスクリーンショット

パーティション分割されるコピーを有効にすると、コピーアクティビティによって Azure Synapse Analytics ソースに対する並列クエリが実行され、パーティションごとにデータが読み込まれます。並列度は、コピーアクティビティの parallelCopies 設定によって制御されます。たとえば、parallelCopies を 4 に設定した場合、サービスでは、指定したパーティションオプションと設定に基づいて 4 つのクエリが同時に生成され、実行されます。そして各クエリが、Azure Synapse Analytics からデータの一部を取得します。

Azure Synapse Analytics から大量のデータを読み込む場合は特に、データパーティション分割を行う並列コピーを有効にすることが推奨されます。さまざまなシナリオの推奨構成を以下に示します。ファイルベースのデータストアにデータをコピーする場合は、複数のファイルとしてフォルダーに書き込む (フォルダー名のみを指定する) ことをお勧めします。この場合、1 つのファイルに書き込むよりもパフォーマンスが優れています。

シナリオ	推奨設定
物理パーティションに分割された大きなテーブル全体から読み込む。	パーティションオプション: テーブルの物理パーティション。実行中に、サービスによって物理パーティションが自動的に検出され、パーティションごとにデータがコピーされます。テーブルに物理パーティションがあるかどうかを確認するには、こちらのクエリを参照してください。
物理パーティションがなく、データパーティション分割用の整数または日時の列がある大きなテーブル全体から読み込む。	パーティションオプション: 動的範囲パーティション。パーティション列 (省略可能):データのパーティション分割に使用される列を指定します。指定されていない場合は、インデックスまたは主キー列が使用されます。パーティションの上限とパーティションの下限 (省略可能):パーティションのストライドを決定する場合に指定します。これは、テーブル内の行のフィルター処理用ではなく、テーブル内のすべての行がパーティション分割されてコピーされます。指定されていない場合は、コピーアクティビティによって値が自動検出されます。たとえば、パーティション列「ID」の値の範囲が 1 ～ 100 で、下限を 20 に、上限を 80 に設定し、並列コピーを 4 にした場合、サービスによって 4 つのパーティションでデータが取得されます。ID の範囲は、それぞれ、20 以下、21 ～ 50、51 ～ 80、81 以上となります。
物理パーティションがなく、データパーティション分割用の整数列または日付/日時列がある大量のデータを、カスタムクエリを使用して読み込む。	パーティションオプション: 動的範囲パーティション。クエリ: `SELECT * FROM <TableName> WHERE ?DfDynamicRangePartitionCondition AND <your_additional_where_clause>` パーティション列: データのパーティション分割に使用される列を指定します。パーティションの上限とパーティションの下限 (省略可能):パーティションのストライドを決定する場合に指定します。これは、テーブル内の行のフィルター処理用ではなく、クエリ結果のすべての行がパーティション分割されてコピーされます。指定されていない場合は、Copy アクティビティによって値が自動検出されます。たとえば、パーティション列「ID」の値の範囲が 1 ～ 100 で、下限を 20 に、上限を 80 に設定し、並列コピーを 4 にした場合、サービスによって 4 つのパーティションでデータが取得されます。ID の範囲は、それぞれ、20 以下、21 ～ 50、51 ～ 80、81 以上となります。さまざまなシナリオのサンプルクエリを次に示します。 1.テーブル全体に対してクエリを実行する: `SELECT * FROM <TableName> WHERE ?DfDynamicRangePartitionCondition` 2.列の選択と追加の where 句フィルターが含まれるテーブルからのクエリ: `SELECT <column_list> FROM <TableName> WHERE ?DfDynamicRangePartitionCondition AND <your_additional_where_clause>` 3.サブクエリを使用したクエリ: `SELECT <column_list> FROM (<your_sub_query>) AS T WHERE ?DfDynamicRangePartitionCondition AND <your_additional_where_clause>` 4.サブクエリにパーティションがあるクエリ: `SELECT <column_list> FROM (SELECT <your_sub_query_column_list> FROM <TableName> WHERE ?DfDynamicRangePartitionCondition) AS T`

パーティションオプションを使用してデータを読み込む場合のベストプラクティス:

データスキューを回避するため、パーティション列 (主キーや一意キーなど) には特徴のある列を選択します。
テーブルに組み込みパーティションがある場合は、パフォーマンスを向上させるためにパーティションオプションとして "テーブルの物理パーティション" を使用します。
Azure Integration Runtime を使用してデータをコピーする場合は、より大きな (4 より大きい) "データ統合単位 (DIU)" (>4) を設定すると、より多くのコンピューティングリソースを利用できます。そこで、該当するシナリオを確認してください。
パーティション数は、"コピーの並列処理の次数" によって制御されます。この数値を大きくしすぎるとパフォーマンスが低下するため、この数値は、(DIU またはセルフホステッド IR ノードの数) x (2 から 4) に設定することをお勧めします。
Azure Synapse Analytics では、最大で 32 個のクエリを実行でき、「コピーの並列度」を高く設定しすぎると、Synapse の調整の問題が発生する可能性があることに注意してください。

例: 複数の物理パーティションがある大きなテーブル全体から読み込む

"source": {
    "type": "SqlDWSource",
    "partitionOption": "PhysicalPartitionsOfTable"
}

例: 動的範囲パーティションを使用してクエリを実行する

"source": {
    "type": "SqlDWSource",
    "query": "SELECT * FROM <TableName> WHERE ?DfDynamicRangePartitionCondition AND <your_additional_where_clause>",
    "partitionOption": "DynamicRange",
    "partitionSettings": {
        "partitionColumnName": "<partition_column_name>",
        "partitionUpperBound": "<upper_value_of_partition_column (optional) to decide the partition stride, not as data filter>",
        "partitionLowerBound": "<lower_value_of_partition_column (optional) to decide the partition stride, not as data filter>"
    }
}

物理パーティションを確認するためのサンプルクエリ

SELECT DISTINCT s.name AS SchemaName, t.name AS TableName, c.name AS ColumnName, CASE WHEN c.name IS NULL THEN 'no' ELSE 'yes' END AS HasPartition
FROM sys.tables AS t
LEFT JOIN sys.objects AS o ON t.object_id = o.object_id
LEFT JOIN sys.schemas AS s ON o.schema_id = s.schema_id
LEFT JOIN sys.indexes AS i ON t.object_id = i.object_id
LEFT JOIN sys.index_columns AS ic ON ic.partition_ordinal > 0 AND ic.index_id = i.index_id AND ic.object_id = t.object_id
LEFT JOIN sys.columns AS c ON c.object_id = ic.object_id AND c.column_id = ic.column_id
LEFT JOIN sys.types AS y ON c.system_type_id = y.system_type_id
WHERE s.name='[your schema]' AND t.name = '[your table name]'

テーブルに物理パーティションがある場合、"HasPartition" は "yes" と表示されます。

COPY ステートメントを使用して Azure Synapse Analytics にデータを読み込む

COPY ステートメントを使用することは、高いスループットで Azure Synapse Analytics にデータを読み込むための単純で柔軟な方法です。詳細については、「COPY ステートメントを使用したデータの一括読み込み」を参照してください

ソースデータが Azure Blob、Azure Data Lake Storage Gen2 内にあるときに、形式が COPY ステートメント互換の場合は、コピーアクティビティを使用して COPY ステートメントを直接呼び出し、Azure Synapse Analytics でソースからデータを引き出すことができます。詳しくは、「 COPY ステートメントを使用して直接コピーする 」をご覧ください。
ソースデータストアと形式が、本来は COPY ステートメントでサポートされていない形式の場合は、代わりに COPY ステートメントを使用したステージングコピー を使います。ステージングコピー機能はスループットも優れています。データは、COPY ステートメントと互換性のある形式に自動的に変換され、Azure Blob Storage に格納されます。その後、COPY ステートメントが呼び出されて、Azure Synapse Analytics にデータが読み込まれます。

ヒント

Azure Integration Runtime で COPY ステートメントを使用する場合、有効なデータ統合単位 (DIU) は常に 2 です。ストレージからのデータの読み込みは Azure Synapse エンジンによって行われるため、DIU をチューニングしてもパフォーマンスには影響しません。

COPY ステートメントを使用した直接コピー

Azure Synapse Analytics の COPY ステートメントでは、Azure Blob、Azure Data Lake Storage Gen1、Azure Data Lake Storage Gen2 が直接サポートされます。ソースデータがこのセクションで説明する条件を満たしている場合は、COPY ステートメントを使用してソースデータストアから Azure Synapse Analytics に直接コピーします。それ以外の場合は、COPY ステートメントを使用したステージングコピーを使います。サービスによって設定が確認され、条件が満たされない場合は、コピーアクティビティの実行が失敗します。

ソースのリンクされたサービスと形式では、次の種類と認証方法が使用されます。

サポートされるソースデータストアの種類	サポートされる形式	サポートされる認証の種類
Azure BLOB	区切りテキスト	アカウントキー認証、Shared Access Signature 認証、サービスプリンシパル認証、システム割り当てマネージド ID 認証
	Parquet	アカウントキー認証、Shared Access Signature 認証
	ORC	アカウントキー認証、Shared Access Signature 認証
Azure Data Lake Storage Gen2	区切りテキスト Parquet ORC	アカウントキー認証、サービスプリンシパル認証、システム割り当てマネージド ID 認証

重要

ストレージのリンクされたサービスに対してマネージド ID 認証を使用する場合は、Azure Blob と Azure Data Lake Storage Gen2 に必要な各構成について確認してください。
Azure Storage が VNet サービスエンドポイントを使用して構成されている場合は、ストレージアカウントで [allow trusted Microsoft service](信頼された Microsoft サービスを許可する) を有効にしたマネージド ID 認証を使用する必要があります。詳細については「Azure Storage で VNet サービスエンドポイントを使用した場合の影響」を参照してください。

形式設定は次のとおりです。
1. Parquet の場合: compression は圧縮なし、Snappy、または GZip に設定できます。
2. ORC の場合: compression が 圧縮なし、 zlib 、または Snappy である。
3. 区切りテキストの場合:
  1. rowDelimiter が単一の文字または " \r\n" として明示的に設定されており、既定値がサポートされていない。
  2. nullValue が既定値のままか、空の文字列 ("") に設定されている。
  3. encodingName が既定値のままか、utf-8 または utf-16 に設定されている。
  4. escapeChar が quoteChar と同じである必要があり、空ではない。
  5. skipLineCount が既定値のままか、0 に設定されている。
  6. compression は圧縮なしまたは GZip に設定できます。
ソースがフォルダーの場合は、コピーアクティビティの recursive を true に設定し、wildcardFilename が * または *.* である必要があります。
wildcardFolderPath、wildcardFilename (* または *.* 以外)、modifiedDateTimeStart、modifiedDateTimeEnd、prefix、enablePartitionDiscovery、additionalColumns は指定されません。

コピーアクティビティの allowCopyCommand では、次の COPY ステートメント設定がサポートされています。

プロパティ	内容	必須
defaultValues	Azure Synapse Analytics の各ターゲット列の既定値を指定します。このプロパティの既定値により、データウェアハウスで設定されている DEFAULT 制約が上書きされます。ID 列に既定値を設定することはできません。	いいえ
additionalOptions	COPY ステートメントの "With" 句で、Azure Synapse Analytics の COPY ステートメントに直接渡される追加オプション。 COPY ステートメントの要件に合わせて、必要に応じて値を引用符で囲みます。	いいえ

"activities":[
    {
        "name": "CopyFromAzureBlobToSQLDataWarehouseViaCOPY",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "ParquetDataset",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "AzureSQLDWDataset",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "ParquetSource",
                "storeSettings":{
                    "type": "AzureBlobStorageReadSettings",
                    "recursive": true
                }
            },
            "sink": {
                "type": "SqlDWSink",
                "allowCopyCommand": true,
                "copyCommandSettings": {
                    "defaultValues": [
                        {
                            "columnName": "col_string",
                            "defaultValue": "DefaultStringValue"
                        }
                    ],
                    "additionalOptions": {
                        "MAXERRORS": "10000",
                        "DATEFORMAT": "'ymd'"
                    }
                }
            },
            "enableSkipIncompatibleRow": true
        }
    }
]

COPY ステートメントを使用したステージングコピー

ソースデータが COPY ステートメントとネイティブに互換性がない場合は、中間ステージング Azure Blob または Azure Data Lake Storage Gen2 を介したデータのコピーを有効にします (Azure Premium Storage は使用できません)。この場合、サービスによって、COPY ステートメントのデータ形式要件を満たすようにデータが自動的に変換されます。そして、COPY ステートメントを起動して、Azure Synapse Analyticsにデータを読み込みます。最後に、ストレージから一時データがクリーンアップされます。ステージング経由でのデータのコピーの詳細は、「ステージングコピー」を参照してください。

この機能を使用するには、中間ストレージとして Azure Storage アカウントを参照するアカウントキーまたはシステムマネージド ID の認証を使用して、Azure Blob Storage のリンクされたサービスまたは Azure Data Lake Storage Gen2 のリンクされたサービスを作成します。

重要

ステージングのリンクされたサービスに対してマネージド ID 認証を使用する場合は Azure Blob と Azure Data Lake Storage Gen2 に必要な各構成について確認してください。また、ステージング Azure Blob Storage または Azure Data Lake Storage Gen2 アカウントで、Azure Synapse Analytics ワークスペースのマネージド ID にアクセス許可を付与する必要もあります。このアクセス許可を付与する方法については、「ワークスペースのマネージド ID にアクセス許可を付与する」を参照してください。
ステージング Azure Storage が VNet サービスエンドポイントを使用して構成されている場合は、ストレージアカウントで [allow trusted Microsoft service](信頼された Microsoft サービスを許可する) を有効にしたマネージド ID 認証を使用する必要があります。詳細については「Azure Storage で VNet サービスエンドポイントを使用した場合の影響」を参照してください。

重要

ステージング Azure Storage がマネージドプライベートエンドポイントで構成され、ストレージファイアウォールが有効になっている場合は、マネージド ID 認証を使用し、Synapse SQL Server にストレージ BLOB データ閲覧者のアクセス許可を付与して、COPY ステートメントの読み込み中にステージングファイルにアクセスできるようにする必要があります。

"activities":[
    {
        "name": "CopyFromSQLServerToSQLDataWarehouseViaCOPYstatement",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "SQLServerDataset",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "AzureSQLDWDataset",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "SqlSource",
            },
            "sink": {
                "type": "SqlDWSink",
                "allowCopyCommand": true
            },
            "stagingSettings": {
                "linkedServiceName": {
                    "referenceName": "MyStagingStorage",
                    "type": "LinkedServiceReference"
                }
            }
        }
    }
]

PolyBase を使用して Azure Synapse Analytics にデータを読み込む

PolyBase を使用すると、高いスループットで Azure Synapse Analytics に大量のデータを効率的に読み込むことができます。既定の BULKINSERT メカニズムではなく PolyBase を使用することで、スループットが大幅に向上することがわかります。

ソースデータが Azure Blob、Azure Data Lake Storage Gen1、または Azure Data Lake Storage Gen2 内にあるときに、形式が PolyBase 互換の場合は、コピーアクティビティを使用して PolyBase を直接呼び出し、Azure Synapse Analytics でソースからデータを引き出すことができます。詳しくは、「 PolyBase を使用して直接コピーする 」をご覧ください。
ソースデータのストアと形式が、本来は PolyBase でサポートされていない形式の場合は、代わりに PolyBase を使用したステージングコピー を使います。ステージングコピー機能はスループットも優れています。データは、PolyBase と互換性のある形式に自動的に変換され、Azure Blob Storage に格納されます。その後、PolyBase が呼び出されて、Azure Synapse Analytics にデータが読み込まれます。

ヒント

「PolyBase の使用に関するベストプラクティス」をご覧ください。 Azure Integration Runtime で PolyBase を使用している場合、直接またはステージングされているストレージから Synapse へのデータ統合ユニット (DIU) は常に 2 になります。ストレージからのデータの読み込みは Synapse エンジンによって行われるため、DIU をチューニングしてもパフォーマンスには影響しません。

コピーアクティビティの polyBaseSettings では、次の PolyBase 設定がサポートされています。

プロパティ	内容	必須
rejectValue	クエリが失敗するまでに拒否できる行の数または割合を指定します。 PolyBase の拒否オプションの詳細については、「CREATE EXTERNAL TABLE (Transact-SQL)」の「引数」セクションを参照してください。使用可能な値は、0 (既定値)、1、2 などです。	いいえ
rejectType	rejectValue オプションがリテラル値か割合かを指定します。使用可能な値は、Value (既定値) と Percentage です。	いいえ
rejectSampleValue	拒否された行の割合が PolyBase で再計算されるまでに取得する行数を決定します。使用可能な値は、1、2 などです。	はい (rejectType が percentage の場合)。
useTypeDefault	PolyBase によってテキストファイルからデータが取得されるときに、区切りテキストファイル内の不足値を処理する方法を指定します。このプロパティの詳細については、CREATE EXTERNAL FILE FORMAT (Transact-SQL) Arguments セクションをご覧ください。使用可能な値: True、および False (既定値)。	いいえ

PolyBase を使用して直接コピーする

Azure Synapse Analytics の PolyBase では、Azure Blob、Azure Data Lake Storage Gen1、および Azure Data Lake Storage Gen2 が直接サポートされます。ソースデータがこのセクションで説明する条件を満たしている場合は、PolyBase を使用してソースデータストアから Azure Synapse Analytics に直接コピーします。それ以外の場合は、PolyBase を使用したステージングコピーを使います。

ヒント

データを効率的に Azure Synapse Analytics にコピーするには、「Azure Data Factory を利用すれば、Azure Synapse Analytics と共に Data Lake Store を使用する場合にデータからさらに容易かつ便利に情報を引き出せるようになる」を参考にしてください。

要件が満たされない場合は、サービスが設定を確認し、データ移動には自動的に BULKINSERT メカニズムが使用されるように戻ります。

ソースリンクサービスでは、次の種類と認証方法が使用されます。

サポートされるソースデータストアの種類	サポートされる認証の種類
Azure BLOB	アカウントキー認証、システム割り当てマネージド ID 認証
Azure Data Lake Storage Gen1	サービスプリンシパルの認証
Azure Data Lake Storage Gen2	アカウントキー認証、システム割り当てマネージド ID 認証

重要

ストレージのリンクされたサービスに対してマネージド ID 認証を使用する場合は、Azure Blob と Azure Data Lake Storage Gen2 に必要な各構成について確認してください。
Azure Storage が VNet サービスエンドポイントを使用して構成されている場合は、ストレージアカウントで [allow trusted Microsoft service](信頼された Microsoft サービスを許可する) を有効にしたマネージド ID 認証を使用する必要があります。詳細については「Azure Storage で VNet サービスエンドポイントを使用した場合の影響」を参照してください。

ソースデータ形式は、次のように構成された Parquet、 ORC、または区切りテキストです。
1. フォルダーのパスにワイルドカードフィルターが含まれない。
2. ファイル名が空か、1 つのファイルを指している。コピーアクティビティでワイルドカードのファイル名を指定する場合は、* または *.* のみを指定できます。
3. rowDelimiter が default、 \n、 \r\n、または \r である。
4. nullValue が既定値のままか、空の文字列 ("") に設定されており、treatEmptyAsNull が既定値のままか、true に設定されている。
5. encodingName が既定値のままか、utf-8 に設定されている。
6. quoteChar、escapeChar、および skipLineCount が指定されていない。 PolyBase では、ヘッダー行のスキップがサポートされます。これは、firstRowAsHeader として構成できます。
7. compression は、圧縮無し、GZip、または Deflate に設定できます。
ソースがフォルダーの場合は、コピーアクティビティの recursive を true に設定する必要があります。
wildcardFolderPath、wildcardFilename、modifiedDateTimeStart、modifiedDateTimeEnd、prefix、enablePartitionDiscovery、additionalColumns は指定されません。

Note

ソースがフォルダーの場合、PolyBase ではフォルダーとそのすべてのサブフォルダーからファイルが取得され、ファイル名の先頭に下線 (_) またはピリオド (.) が付いているファイルからはデータが取得されないことに注意してください。詳細については、LOCATION 引数に関するこちらのドキュメントを参照してください。

"activities":[
    {
        "name": "CopyFromAzureBlobToSQLDataWarehouseViaPolyBase",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "ParquetDataset",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "AzureSQLDWDataset",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "ParquetSource",
                "storeSettings":{
                    "type": "AzureBlobStorageReadSettings",
                    "recursive": true
                }
            },
            "sink": {
                "type": "SqlDWSink",
                "allowPolyBase": true
            }
        }
    }
]

PolyBase を使用したステージングコピー

ソースデータが PolyBase とネイティブに互換性がない場合は、中間ステージング Azure Blob または Azure Data Lake Storage Gen2 を介したデータのコピーを有効にします (Azure Premium Storage は使用できません)。この場合、サービスによって、PolyBase のデータ形式要件を満たすようにデータが自動的に変換されます。その後、PolyBase を使用して、データが Azure Synapse Analytics に読み込まれます。最後に、ストレージから一時データがクリーンアップされます。ステージング経由でのデータのコピーの詳細は、「ステージングコピー」を参照してください。

この機能を使用するには、中間ストレージとして Azure Storage アカウントを参照するアカウントキーまたはマネージド ID の認証を使用して、Azure Blob Storage のリンクされたサービスまたは Azure Data Lake Storage Gen2 のリンクされたサービスを作成します。

重要

ステージングのリンクされたサービスに対してマネージド ID 認証を使用する場合は Azure Blob と Azure Data Lake Storage Gen2 に必要な各構成について確認してください。また、ステージング Azure Blob Storage または Azure Data Lake Storage Gen2 アカウントで、Azure Synapse Analytics ワークスペースのマネージド ID にアクセス許可を付与する必要もあります。このアクセス許可を付与する方法については、「ワークスペースのマネージド ID にアクセス許可を付与する」を参照してください。
ステージング Azure Storage が VNet サービスエンドポイントを使用して構成されている場合は、ストレージアカウントで [allow trusted Microsoft service](信頼された Microsoft サービスを許可する) を有効にしたマネージド ID 認証を使用する必要があります。詳細については「Azure Storage で VNet サービスエンドポイントを使用した場合の影響」を参照してください。

重要

ステージング Azure Storage がマネージドプライベートエンドポイントで構成され、ストレージファイアウォールが有効になっている場合は、マネージド ID 認証を使用し、Synapse SQL Server にストレージ BLOB データ閲覧者のアクセス許可を付与して、PolyBase の読み込み中にステージングファイルにアクセスできるようにする必要があります。

"activities":[
    {
        "name": "CopyFromSQLServerToSQLDataWarehouseViaPolyBase",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "SQLServerDataset",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "AzureSQLDWDataset",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "SqlSource",
            },
            "sink": {
                "type": "SqlDWSink",
                "allowPolyBase": true
            },
            "enableStaging": true,
            "stagingSettings": {
                "linkedServiceName": {
                    "referenceName": "MyStagingStorage",
                    "type": "LinkedServiceReference"
                }
            }
        }
    }
]

PolyBase の使用に関するベストプラクティス

次のセクションでは、Azure Synapse Analytics のベストプラクティスに関する記事に記載されているもの以外のベストプラクティスについて説明します。

必要なデータベースアクセス許可

PolyBase を使用するには、データを Azure Synapse Analytics に読み込むユーザーは、ターゲットデータベースに対する "CONTROL" アクセス許可を持っている必要があります。これを実現する方法の 1 つは、ユーザーを db_owner ロールのメンバーとして追加することです。これを行う方法については、Azure Synapse Analytics の概要に関する記事を参照してください。

行のサイズとデータ型の制限

PolyBase の読み込みは、1 MB 未満の行に制限されます。 VARCHR(MAX)、NVARCHAR(MAX)、VARBINARY(MAX) への読み込みには使用できません。詳細については、「Azure Synapse Analytics サービスの容量制限」を参照してください。

ソースデータに 1 MB を超える行がある場合は、ソーステーブルを複数の小さいテーブルに垂直分割できます。各行の最大サイズが制限を超えないことを確認します。その後、これらの小さいテーブルは、PolyBase を使用して Azure Synapse Analytics に読み込み、マージすることができます。

または、このように広い列を持つデータについては、[Allow polybase (PolyBase を許可する)] 設定をオフにすることで、データの読み込みに PolyBase 以外を使用できます。

Azure Synapse Analytics リソースクラス

可能な限りスループットを最大化するには、PolyBase 経由で Azure Synapse Analytics にデータを読み込むユーザーに、より大きなリソースクラスを割り当てます。

PolyBase に関するトラブルシューティング

10 進数の列への読み込み

ソースデータがテキスト形式であるか、(ステージングコピーと PolyBase を使用する) その他の PolyBase 非互換ストアにあるときに、その中に Azure Synapse Analytics の 10 進数の列に読み込まれる空の値が含まれている場合は、次のエラーが発生することがあります。

ErrorCode=FailedDbOperation, ......HadoopSqlException: Error converting data type VARCHAR to DECIMAL.....Detailed Message=Empty string can't be converted to DECIMAL.....

これを解決するには、コピーアクティビティの sink の PolyBase 設定で、(false として) "型の既定を使用する" オプションを選択解除します。 "USE_TYPE_DEFAULT" は、PolyBase でテキストファイルからデータが取得される際に区切りテキストファイル内の欠落値を処理する方法を指定する PolyBase ネイティブ構成です。

Azure Synapse Analytics で tableName プロパティを確認する

次の表は、JSON データセットで tableName プロパティを指定する方法の例です。スキーマとテーブル名の複数の組み合わせを示します。

DB スキーマ	テーブル名	tableName JSON プロパティ
dbo	MyTable	MyTable、dbo.MyTable、または [dbo].[MyTable]
dbo1	MyTable	dbo1.MyTable または [dbo1].[MyTable]
dbo	My.Table	[My.Table] または [dbo].[My.Table]
dbo1	My.Table	[dbo1].[My.Table]

次のエラーが表示される場合は、tableName プロパティに指定した値に問題がある可能性があります。 tableName JSON プロパティの値を指定する正しい方法については、上の表を参照してください。

Type=System.Data.SqlClient.SqlException,Message=Invalid object name 'stg.Account_test'.,Source=.Net SqlClient Data Provider

既定値を持つ列

現在、PolyBase 機能では、ターゲットテーブルと同じ数の列のみを使用できます。たとえば、4 つの列を含むテーブルがあり、その列の 1 つには既定値が定義されているものとします。それでも入力データには 4 つの列が必要です。入力データセットが 3 列の場合は、次のメッセージのようなエラーが発生します。

All columns of the table must be specified in the INSERT BULK statement.

null 値は、特殊な形式の既定値です。列が null 許容の場合、その列に対する BLOB 内の入力データが空になる可能性があります。ただし、入力データセットから欠落することはできません。 PolyBase では、Azure Synapse Analytics の欠損値に対して null を挿入します。

外部ファイルへのアクセスに失敗する

次のエラーが発生した場合は、マネージド ID 認証を使用していること、および Synapse SQL Server ワークスペースのマネージド ID にストレージ BLOB データ閲覧者のアクセス許可が付与されていることを確認してください。

Job failed due to reason: at Sink '[SinkName]': shaded.msdataflow.com.microsoft.sqlserver.jdbc.SQLServerException: External file access failed due to internal error: 'Error occurred while accessing HDFS: Java exception raised on call to HdfsBridge_IsDirExist. Java exception message:\r\nHdfsBridge::isDirExist

詳細については、「ワークスペースの作成後にマネージド ID にアクセス許可を付与する」を参照してください。

Mapping Data Flow のプロパティ

マッピングデータフローでデータを変換する場合、Azure Synapse Analytics からテーブルの読み取りと書き込みを実行できます。詳細については、マッピングデータフローのソース変換とシンク変換に関する記事をご覧ください。

ソース変換

Azure Synapse Analytics に固有の設定は、ソース変換の [Source Options](ソースオプション) タブにあります。

[入力](Input) : テーブルにあるソースを指す (Select * from <table-name> に相当) かカスタム SQL クエリを入力するかを選択します。

[Enable Staging](ステージングを有効にする) Azure Synapse Analytics ソースを使用する運用ワークロードでは、このオプションを使用することを強くお勧めします。パイプラインから Azure Synapse Analytics ソースを使用してデータフローアクティビティを実行すると、ステージングデータの読み込みに使用されるステージング場所のストレージアカウントの入力が求められます。 Azure Synapse Analytics からデータを読み込む最も速いメカニズムです。

ストレージのリンクされたサービスに対してマネージド ID 認証を使用する場合は、Azure Blob と Azure Data Lake Storage Gen2 に必要な各構成について確認してください。
Azure Storage が VNet サービスエンドポイントを使用して構成されている場合は、ストレージアカウントで [allow trusted Microsoft service](信頼された Microsoft サービスを許可する) を有効にしたマネージド ID 認証を使用する必要があります。詳細については「Azure Storage で VNet サービスエンドポイントを使用した場合の影響」を参照してください。
Azure Synapse サーバーレス SQL プールをソースとして使用する場合、ステージングの有効化はサポートされていません。

Query: [Input] フィールドで [Query] を選択した場合は、ソースに対する SQL クエリを入力します。この設定により、データセットで選択したすべてのテーブルがオーバーライドされます。ここでは Order By 句はサポートされていませんが、完全な SELECT FROM ステートメントを設定することができます。ユーザー定義のテーブル関数を使用することもできます。 select * from udfGetData() は、テーブルを返す SQL の UDF です。このクエリでは、お使いのデータフローで使用できるソーステーブルが生成されます。テスト対象またはルックアップ対象の行を減らすうえでも、クエリの使用は有効な手段です。

SQL の例: Select * from MyTable where customerId > 1000 and customerId < 2000

Batch size: 大量データを読み取りにまとめるバッチサイズを入力します。データフローでは、この設定は Spark 列キャッシングの設定に使用されます。これは省略可能なフィールドであり、空白のままになっている場合は Spark の既定値が使用されます。

Isolation Level: マッピングデータフローでの SQL ソースの既定値は [コミットされていないものを読み取り] です。ここで分離レベルを次のいずれかの値に変更できます。

コミットされたものを読み取り
コミットされていないものを読み取り
反復可能読み取り
シリアル化可能
なし (分離レベルを無視)

Isolation Level

シンク変換

Azure Synapse Analytics に固有の設定は、シンク変換の [設定] タブにあります。

[Update method](更新方法) : 対象となるデータベースに対して許可される操作を指定します。既定では、挿入のみが許可されます。行を更新、アップサート、または削除するには、それらのアクションに対して行をタグ付けするために行の変更変換が必要になります。更新、アップサート、削除の場合、1 つまたは複数のキー列を設定して、変更する行を決定する必要があります。

[Table action](テーブルアクション): 書き込み前に変換先テーブルのすべての行を再作成するか削除するかを指定します。

[なし]:テーブルに対してアクションは実行されません。
[再作成]:テーブルが削除され、再作成されます。新しいテーブルを動的に作成する場合に必要です。
[切り詰め]:ターゲットテーブルのすべての行が削除されます。

ステージングを有効にする: これにより、copy コマンドを使用して Azure Synapse Analytics SQL プールに読み込むことができます。ほとんどの Synpase シンクでは、この方法をお勧めします。ステージングストレージはデータフローの実行アクティビティで構成されます。

ストレージのリンクされたサービスに対してマネージド ID 認証を使用する場合は、Azure Blob と Azure Data Lake Storage Gen2 に必要な各構成について確認してください。
Azure Storage が VNet サービスエンドポイントを使用して構成されている場合は、ストレージアカウントで [allow trusted Microsoft service](信頼された Microsoft サービスを許可する) を有効にしたマネージド ID 認証を使用する必要があります。詳細については「Azure Storage で VNet サービスエンドポイントを使用した場合の影響」を参照してください。

Batch size: 各バケットに書き込まれる行数を制御します。バッチサイズを大きくすると、圧縮とメモリの最適化が向上しますが、データをキャッシュする際にメモリ不足の例外が発生するリスクがあります。

シンクスキーマを使用する: 既定では、シンクスキーマの下にステージングとして一時テーブルが作成されます。または、[シンクスキーマを使用する] オプションをオフにして、[ユーザー DB スキーマの選択] で、Data Factory でステージングテーブルを作成してアップストリームデータを読み込み、完了時に自動的にクリーンアップするスキーマ名を指定することもできます。データベースにテーブルの作成権限があり、スキーマに対する変更権限があることを確認します。

データフロー 'シンクスキーマを使用する' を示しているスクリーンショット。

[Pre and Post SQL scripts] (事前および事後 SQL スクリプト) : データがシンクデータベースに書き込まれる前 (前処理) と書き込まれた後 (後処理) に実行される複数行の SQL スクリプトを入力します。

Azure Synapse Analytics の処理前および処理後の SQL スクリプトを示しているスクリーンショット。

ヒント

複数のコマンドを含む単一のバッチスクリプトを複数のバッチに分割することをお勧めします。
バッチの一部として実行できるのは、単純に更新数を返すデータ操作言語 (DML) ステートメントおよびデータ定義言語 (DDL) ステートメントだけです。詳細については、「バッチ操作の実行」を参照してください。

エラー行の処理

Azure Synapse Analytics に書き込む場合、書き込み先で設定されている制約によって、データの特定の行が失敗することがあります。一般的なエラーには次のようなものがあります。

テーブル内の文字列データまたはバイナリデータが切り捨てられる
列に値 NULL を挿入できない
値をデータ型に変換できない

既定では、データフローの実行は最初に発生したエラーで失敗します。 [エラーのまま続行する] を選択すると、個々の行でエラーが発生した場合でもデータフローを完了することができます。サービスには、これらのエラー行を処理するためのさまざまなオプションが用意されています。

[Transaction Commit](トランザクションコミット): データを 1 つのトランザクションまたはバッチのどちらで書き込むかを選択します。 1 つのトランザクションの場合はパフォーマンスが向上し、トランザクションが完了するまで書き込みデータは他のユーザーに表示されません。バッチトランザクションのパフォーマンスは低下しますが、大規模なデータセットを扱うことができます。

[Output rejected data](拒否されたデータの出力): 有効にすると、エラー行を Azure Blob Storage または選択した Azure Data Lake Storage Gen2 アカウントの csv ファイルに出力できます。これにより、3 つの列 (INSERT または UPDATE などの SQL 操作、データフローエラーコード、および行のエラーメッセージ) を含むエラー行が書き込まれます。

[Report success on error](エラー発生時に成功を報告): 有効にすると、エラー行が見つかった場合でもデータフローは成功としてマークされます。

マッピングデータフローシンク変換のエラー行処理を示す図。

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

プロパティの詳細については、Lookup アクティビティに関するページを参照してください。

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

プロパティの詳細については、GetMetadata アクティビティに関するページを参照してください。

Azure Synapse Analytics のデータ型のマッピング

Azure Synapse Analytics との間でデータをコピーする場合、Azure Synapse Analytics のデータ型から Azure Data Factory の中間データ型への次のマッピングが使用されます。これらのマッピングは、Synapse パイプラインを使用して Azure Synapse Analytics との間でデータをコピーするときにも使用されます。これは、パイプラインも Azure Synapse 内で Azure Data Factory を実装するためです。コピーアクティビティでソースのスキーマとデータ型がシンクにマッピングされるしくみについては、スキーマとデータ型のマッピングに関する記事を参照してください。

ヒント

Azure Synapse Analytics でサポートされているデータ型と、サポートされていないデータ型への対処法については、Azure Synapse Analytics のテーブルのデータ型に関する記事をご覧ください。

Azure Synapse Analytics のデータ型	Data Factory の中間データ型
bigint	Int64
binary	Byte[]
bit	Boolean
char	String, Char[]
date	DateTime
Datetime	DateTime
datetime2	DateTime
Datetimeoffset	DateTimeOffset
Decimal	Decimal (10 進数型)
FILESTREAM attribute (varbinary(max))	Byte[]
Float	Double
image	Byte[]
INT	Int32
money	Decimal (10 進数型)
nchar	String, Char[]
numeric	Decimal (10 進数型)
nvarchar	String, Char[]
real	Single
rowversion	Byte[]
smalldatetime	DateTime
smallint	Int16
smallmoney	Decimal
time	TimeSpan
tinyint	Byte
UNIQUEIDENTIFIER	Guid
varbinary	Byte[]
varchar	String, Char[]

コピーアクティビティによってソース、シンクとしてサポートされるデータストアの一覧については、サポートされるデータストアと形式の表を参照してください。