次の方法で共有

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

  • [アーティクル]

適用対象: 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 のリンク サービスを作成します。

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

  2. Synapse を検索し、Azure Synapse Analytics コネクタを選択します。

    Azure Synapse Analytics コネクタのスクリーンショット。

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

    Azure Synapse Analytics のリンク サービスの構成のスクリーンショット。

コネクタの構成の詳細

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

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

Azure Synapse Analytics コネクタの推奨バージョンでは、TLS 1.3 がサポートされています。 Azure Synapse Analytics コネクタのバージョンをレガシのものからアップグレードするには、このセクションを参照してください。 プロパティの詳細については、対応するセクションを参照してください。

ヒント

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

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

ヒント

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

推奨バージョンを適用すると、次の汎用プロパティが Azure Synapse Analytics のリンク サービスでサポートされます。

プロパティ 内容 必須
type type プロパティは AzureSqlDW に設定する必要があります。 はい
サーバー 接続先の SQL Server インスタンスの名前またはネットワーク アドレス。 はい
database データベースの名前。 はい
authenticationType 認証に使用される型。 使用できる値は、SQL (既定値)、ServicePrincipal、SystemAssignedManagedIdentity、UserAssignedManagedIdentity です。 特定のプロパティと前提条件に関する関連する認証セクションに移動します。 はい
encrypt クライアントとサーバーの間で送信されるすべてのデータに TLS 暗号化が必要かどうかを示します。 オプション: 必須 (true の場合、既定値)/省略可能 (false の場合)/strict。 いいえ
trustServerCertificate 信頼を検証するための証明書チェーンをバイパスする間、チャネルが暗号化されるかどうかを示します。 いいえ
hostNameInCertificate 接続のサーバー証明書を検証するときに使用するホスト名。 指定しない場合、サーバー名が証明書の検証に使用されます。 いいえ
connectVia データ ストアに接続するために使用される統合ランタイム。 Azure Integration Runtime またはセルフホステッド統合ランタイムを使用できます (データ ストアがプライベート ネットワークにある場合)。 指定されていない場合は、既定の Azure 統合ランタイムが使用されます。 いいえ

その他の接続プロパティについては、次の表を参照してください。

プロパティ 内容 必須
applicationIntent サーバーに接続するときのアプリケーションのワークロードの種類。 使用できる値は ReadOnly と ReadWrite です。 いいえ
connectTimeout 試行を終了してエラーを生成するまでに、サーバーへの接続を待機する時間 (秒)。 いいえ
connectRetryCount アイドル状態の接続の失敗を特定した後に試された再接続の数。 値は 0 から 255 までの整数である必要があります。 いいえ
connectRetryInterval アイドル状態の接続エラーを特定した後の、再接続試行の時間間隔 (秒)。 SQL Server のバージョンをアップグレードする値は 1 から 60 までの整数である必要があります。 いいえ
loadBalanceTimeout 接続が破棄される前に接続が接続プールに存在する最小時間 (秒)。 いいえ
commandTimeout コマンド実行の試行を終了してエラーを生成するまでの既定の待機時間 (秒)。 いいえ
integratedSecurity 使用できる値は true または false です。 false を指定する場合は、接続に userName とパスワードが指定されるかどうかを示します。 true を指定する場合は、現在の Windows アカウントの資格情報が認証に使用されるかどうかを示します。 いいえ
failoverPartner プライマリ サーバーがダウンしている場合に接続するパートナー サーバーの名前またはアドレス。 いいえ
maxPoolSize 特定の接続について、接続プールで許可される接続の最大数。 いいえ
minPoolSize 特定の接続について、接続プールで許可される接続の最小数。 いいえ
multipleActiveResultSets 使用できる値は true または false です。 true を指定すると、アプリケーションは複数のアクティブな結果セット (MARS) を維持できます。 false を指定すると、アプリケーションは、その接続で他のバッチを実行する前に、1 つのバッチからすべての結果セットを処理または取り消す必要があります。 いいえ
multiSubnetFailover 使用できる値は true または false です。 アプリケーションが異なるサブネット上の AlwaysOn 可用性グループ (AG) に接続する場合、このプロパティを true に設定すると、現在アクティブなサーバーの検出と接続が速くなります。 いいえ
packetSize サーバーのインスタンスとの通信に使用されるネットワーク パケットのサイズ (バイト)。 いいえ
プール 使用できる値は true または false です。 true を指定すると、接続がプールされます。 false を指定すると、接続が要求されるたびに接続が明示的に開かれます。 いいえ

SQL 認証

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

プロパティ 内容 必要
userName サーバーへの接続に使用されるユーザー名。 はい
password 該当するユーザー名のパスワード。 安全に保存するには、このフィールドを SecureString としてマークします。 また、Azure Key Vault に格納されているシークレットを参照することもできます。 はい

例: SQL 認証の使用

{
    "name": "AzureSqlDWLinkedService",
    "properties": {
        "type": "AzureSqlDW",
        "typeProperties": {
            "server": "<name or network address of the SQL server instance>",
            "database": "<database name>",
            "encrypt": "<encrypt>",
            "trustServerCertificate": false,
            "authenticationType": "SQL",
            "userName": "<user name>",
            "password": {
                "type": "SecureString",
                "value": "<password>"
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

例: Azure Key Vault 内のパスワード

{
    "name": "AzureSqlDWLinkedService",
    "properties": {
        "type": "AzureSqlDW",
        "typeProperties": {
            "server": "<name or network address of the SQL server instance>",
            "database": "<database name>",
            "encrypt": "<encrypt>",
            "trustServerCertificate": false,
            "authenticationType": "SQL",
            "userName": "<user name>",
            "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 を取得します。 はい
servicePrincipalCredential サービス プリンシパルの資格情報。 アプリケーションのキーを取得します。 このフィールドを SecureString とマークして安全に保存するか、Azure Key Vault に保存されているシークレットを参照します。 はい
tenant アプリケーションが存在するテナントの情報 (ドメイン名またはテナント ID) を指定します。 Azure Portal の右上隅にマウスを置くことで取得できます。 はい
azureCloudType サービス プリンシパル認証の場合に、Microsoft Entra アプリケーションが登録されている Azure クラウド環境の種類を指定します。
使用できる値は、AzurePublic、AzureChina、AzureUsGovernment、AzureGermany です。 既定では、データ ファクトリまたは Synapse パイプラインのクラウド環境が使用されます。		 いいえ

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

  1. Azure portal から Microsoft Entra アプリケーションを作成します。 アプリケーション名と、リンクされたサービスを定義する次の値を記録しておきます。

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

  2. まだ行っていない場合は、Azure portal でサーバーの Microsoft Entra 管理者をプロビジョニングします。 Microsoft Entra ユーザーまたは Microsoft Entra グループを、Microsoft Entra 管理者にすることができます。 マネージド ID を持つグループに管理者ロールを付与する場合は、ステップ 3 と 4 をスキップします。 管理者は、データベースへのフル アクセスを持ちます。

  3. サービス プリンシパルの 包含データベース ユーザーを作成します 。 SSMS のようなツールと、少なくとも ALTER ANY USER アクセス許可を持つ Microsoft Entra の ID を使って、データをコピーするデータ ウェアハウスに接続します。 次の T-SQL を実行します。

    CREATE USER [your_application_name] FROM EXTERNAL PROVIDER;

  4. SQL ユーザーや他のユーザーに対する通常の方法で、サービス プリンシパルに必要なアクセス許可を付与します。 次のコードを実行するか、こちらでその他のオプションを参照してください。 PolyBase を使用してデータを読み込む場合は、必要なデータベース アクセス許可について学習します。

    EXEC sp_addrolemember db_owner, [your application name];

  5. 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>",
            "servicePrincipalCredential": {
                "type": "SecureString",
                "value": "<application 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 認証を使用するには、前のセクションで説明した汎用プロパティを指定し、次の手順に従います。

  1. まだ行っていない場合は、Azure portal でサーバーの Microsoft Entra 管理者をプロビジョニングします。 Microsoft Entra ユーザーまたは Microsoft Entra グループを、Microsoft Entra 管理者にすることができます。 システム割り当てマネージド ID を持つグループに管理者ロールを付与する場合は、ステップ 3 および 4 をスキップします。 管理者は、データベースへのフル アクセスを持ちます。

  2. システム割り当てマネージド ID の包含データベース ユーザーを作成します。 SSMS のようなツールと、少なくとも ALTER ANY USER アクセス許可を持つ Microsoft Entra の ID を使って、データをコピーするデータ ウェアハウスに接続します。 次の T-SQL を実行します。

    CREATE USER [your_resource_name] FROM EXTERNAL PROVIDER;

  3. 通常の SQL ユーザーなどと同様に、システム割り当てマネージド ID に必要なアクセス許可を付与します。 次のコードを実行するか、こちらでその他のオプションを参照してください。 PolyBase を使用してデータを読み込む場合は、必要なデータベース アクセス許可について学習します。

    EXEC sp_addrolemember db_owner, [your_resource_name];

  4. Azure Synapse Analytics のリンクされたサービスを作成する。

例:

{
    "name": "AzureSqlDWLinkedService",
    "properties": {
        "type": "AzureSqlDW",
        "typeProperties": {
            "server": "<name or network address of the SQL server instance>",
            "database": "<database name>",
            "encrypt": "<encrypt>",
            "trustServerCertificate": false,
            "authenticationType": "SystemAssignedManagedIdentity"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

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

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

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

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

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

  1. まだ行っていない場合は、Azure portal でサーバーの Microsoft Entra 管理者をプロビジョニングします。 Microsoft Entra ユーザーまたは Microsoft Entra グループを、Microsoft Entra 管理者にすることができます。 ユーザー割り当てマネージド ID を持つグループに管理者ロールを付与する場合は、ステップ 3 をスキップします。 管理者は、データベースへのフル アクセスを持ちます。

  2. ユーザー割り当てマネージド ID の包含データベース ユーザーを作成します。 SSMS のようなツールと、少なくとも ALTER ANY USER アクセス許可を持つ Microsoft Entra の ID を使って、データをコピーするデータ ウェアハウスに接続します。 次の T-SQL を実行します。

    CREATE USER [your_resource_name] FROM EXTERNAL PROVIDER;

  3. 1 つ以上のユーザー割り当てマネージド ID を作成し、通常の SQL ユーザーなどと同様に、ユーザー割り当てマネージド ID に必要なアクセス許可を付与します。 次のコードを実行するか、こちらでその他のオプションを参照してください。 PolyBase を使用してデータを読み込む場合は、必要なデータベース アクセス許可について学習します。

    EXEC sp_addrolemember db_owner, [your_resource_name];

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

  5. Azure Synapse Analytics のリンクされたサービスを作成する。

例

{
    "name": "AzureSqlDWLinkedService",
    "properties": {
        "type": "AzureSqlDW",
        "typeProperties": {
            "server": "<name or network address of the SQL server instance>",
            "database": "<database name>",
            "encrypt": "<encrypt>",
            "trustServerCertificate": false,
            "authenticationType": "UserAssignedManagedIdentity",
            "credential": {
                "referenceName": "credential1",
                "type": "CredentialReference"
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

レガシ バージョン

レガシ バージョンを適用すると、次の汎用プロパティが Azure Synapse Analytics のリンク サービスでサポートされます。

プロパティ 内容 必須
type type プロパティは AzureSqlDW に設定する必要があります。 はい
connectionString connectionString プロパティには、Azure Synapse Analytics インスタンスに接続するために必要な情報を指定します。
安全に格納するには、このフィールドを SecureString とマークします。 パスワード/サービス プリンシパル キーを Azure Key Vault に格納して、それが SQL 認証の場合は接続文字列から password 構成をプルすることもできます。 詳細については、「Azure Key Vault への資格情報の格納」の記事を参照してください。		 はい
connectVia データ ストアに接続するために使用される統合ランタイム。 Azure Integration Runtime またはセルフホステッド統合ランタイムを使用できます (データ ストアがプライベート ネットワークにある場合)。 指定されていない場合は、既定の Azure 統合ランタイムが使用されます。 いいえ

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

レガシ バージョンの SQL 認証

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

レガシ バージョンのサービス プリンシパル認証

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

プロパティ 内容 必須
servicePrincipalId アプリケーションのクライアント ID を取得します。 はい
servicePrincipalKey アプリケーションのキーを取得します。 このフィールドを SecureString とマークして安全に保存するか、Azure Key Vault に保存されているシークレットを参照します。 はい
tenant ドメイン名やテナント ID など、アプリケーションが存在するテナントの情報を指定します。 これは、Azure portal の右上隅をマウスでポイントすることで取得できます。 はい
azureCloudType サービス プリンシパル認証用に、Microsoft Entra アプリケーションが登録されている Azure クラウド環境の種類を指定します。
指定できる値は、AzurePublic、AzureChina、AzureUsGovernment、および AzureGermany です。 既定では、データ ファクトリまたは Synapse パイプラインのクラウド環境が使用されます。		 いいえ

また、サービス プリンシパル認証の手順に従って、対応するアクセス許可を付与する必要もあります。

レガシ バージョンのシステム割り当てマネージド ID 認証

システム割り当てマネージド ID 認証を使用するには、「システム割り当てマネージド ID 認証」の推奨バージョンと同じ手順に従います。

レガシ バージョンのユーザー割り当てマネージド ID 認証

ユーザー割り当てマネージド ID 認証を使用するには、「ユーザー割り当てマネージド ID 認証」の推奨バージョンと同じ手順に従います。

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

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

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 を使用することです。

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 Synapse Analytics にデータを読み込むコピー アクティビティの書き込み動作を指定します。
使用できる値は、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

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

  1. データ スキューを回避するため、パーティション列 (主キーや一意キーなど) には特徴のある列を選択します。
  2. テーブルに組み込みパーティションがある場合は、パフォーマンスを向上させるためにパーティション オプションとして "テーブルの物理パーティション" を使用します。
  3. Azure Integration Runtime を使用してデータをコピーする場合は、より大きな (4 より大きい) "データ統合単位 (DIU)" (>4) を設定すると、より多くのコンピューティング リソースを利用できます。 そこで、該当するシナリオを確認してください。
  4. パーティション数は、"コピーの並列処理の次数" によって制御されます。この数値を大きくしすぎるとパフォーマンスが低下するため、この数値は、(DIU またはセルフホステッド IR ノードの数) x (2 から 4) に設定することをお勧めします。
  5. 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 Gen2 が直接サポートされています。 ソース データがこのセクションで説明する条件を満たしている場合は、COPY ステートメントを使用してソース データ ストアから Azure Synapse Analytics に直接コピーします。 それ以外の場合は、COPY ステートメントを使用したステージング コピーを使います。 サービスによって設定が確認され、条件が満たされない場合、Copy アクティビティの実行は失敗します。

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

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

    重要

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

  2. 形式設定は次のとおりです。

    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 に設定できます。

  3. ソースがフォルダーの場合は、コピー アクティビティの recursive を true に設定し、wildcardFilename が * または *.* である必要があります。

  4. 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 Gen2 内にあるときに、形式が PolyBase 互換の場合は、Copy アクティビティを使用して 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 Gen2 を直接サポートしています。 ソース データがこのセクションで説明する条件を満たしている場合は、PolyBase を使用してソース データ ストアから Azure Synapse Analytics に直接コピーします。 それ以外の場合は、PolyBase を使用したステージング コピーを使います。

ヒント

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

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

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

    サポートされるソース データ ストアの種類 サポートされる認証の種類
    Azure BLOB アカウント キー認証、システム割り当てマネージド ID 認証
    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 サービス エンドポイントを使用した場合の影響」を参照してください。

  2. ソース データ形式は、次のように構成された 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 に設定できます。

  3. ソースがフォルダーの場合は、コピー アクティビティの recursive を true に設定する必要があります。

  4. 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 スクリプトを示しているスクリーンショット。

ヒント

  1. 複数のコマンドを含む単一のバッチ スクリプトを複数のバッチに分割することをお勧めします。
  2. バッチの一部として実行できるのは、単純に更新数を返すデータ操作言語 (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[]

Azure Synapse Analytics バージョンをアップグレードする

Azure Synapse Analytics のバージョンをアップグレードするには、[リンク サービスの編集] ページで [バージョン] の [推奨] を選択し、推奨バージョンのリンク サービス プロパティを参照してリンク サービスを構成します。

以下の表は、推奨バージョンとレガシ バージョンを使用する Azure Synapse Analytics の違いを示したものです。

推奨されるバージョン レガシ バージョン
encrypt を strict とすることで TLS 1.3 をサポートします。 TLS 1.3 はサポートされません。

関連するコンテンツ

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