Azure Data Factory または Synapse パイプラインを使用してAzure Synapse Analytics内のデータをコピーおよび変換する

適用対象: Azure Data Factory Azure Synapse Analytics

この記事では、Azure Data Factory パイプラインまたは Synapse パイプラインでコピー アクティビティを使用して、Azure Synapse Analyticsとの間でデータをコピーし、Data Flowを使用してAzure Data Lake Storage Gen2内のデータを変換する方法について説明します。 Azure Data Factoryの詳細については、概要に関する記事を参照してください。

サポートされる機能

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

(1) Azure統合ランタイム (2) セルフホステッド統合ランタイム

Copy アクティビティの場合、このAzure Synapse Analytics コネクタは次の関数をサポートします。

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

概要

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

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

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

Azure ポータル UI でAzure Synapse Analyticsリンクされたサービスを作成するには、次の手順に従います。

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

   • Azure Data Factory
   • Azure Synapse

   Azure Data Factory UI を使用した新しいリンク サービスの作成のスクリーンショット

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

   &&&Azure Synapse Analytics connector&のスクリーンショット&&

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

   

コネクタの構成の詳細

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

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

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

• 推奨されるバージョン
• レガシ バージョン

推奨されるバージョン

これらのジェネリック プロパティは、Recommended バージョンを適用する場合にAzure Synapse Analyticsリンクされたサービスでサポートされます。

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

SQL 認証

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

例: 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"
        }
    }
}

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

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

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

1. Azure ポータルから 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 は、Azure Synapse Analytics認証に使用できます。 指定されたリソースは、この ID を使用してデータ ウェアハウスにアクセスし、データを双方向にコピーできます。

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

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

2. システム割り当てマネージド ID の包含データベース ユーザーを作成します。 SSMS などのツールを使用して、少なくとも ALTER ANY USER アクセス許可を持つ Microsoft Entra アイデンティティを使い、データをコピーするために、コピー元またはコピー先のデータウェアハウスに接続します。 次の 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 認証を使用するには、次のプロパティを指定します。

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

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

2. ユーザー割り当てマネージド ID の包含データベース ユーザーを作成します。 SSMS などのツールを使用して、Microsoft Entra ID を持ち、少なくとも ALTER ANY USER アクセス許可を持った状態で、データをコピーしたいデータウェアハウスの参照元または参照先に接続します。 次の 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"
        }
    }
}

レガシ バージョン

これらのジェネリック プロパティは、Legacy バージョンを適用するときに、Azure Synapse Analyticsのリンクされたサービスでサポートされます。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{
    "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からデータをコピーするには、コピー アクティビティ ソースの type プロパティを SqlDWSource に設定します。 コピー アクティビティの source セクションでは、次のプロパティがサポートされます。

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

• ソースのストアド プロシージャを使用してデータを取得する場合、異なるパラメーター値が渡されたときに別のスキーマを返すようにストアド プロシージャが設計されていると、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 セクションでは、次のプロパティがサポートされます。

例 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 つのファイルに書き込むよりもパフォーマンスが優れています。

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

1. データ スキューを回避するため、パーティション列 (主キーや一意キーなど) には特徴のある列を選択します。
2. テーブルに組み込みパーティションがある場合は、パフォーマンスを向上させるためにパーティション オプションとして "テーブルの物理パーティション" を使用します。
3. Azure Integration Runtimeを使用してデータをコピーする場合は、より大きな "Data Integration Units (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 にあり、format が COPY ステートメントと互換性がある場合<>コピー アクティビティを使用して COPY ステートメントを直接呼び出し、Azure Synapse Analyticsソースからデータをプルできます。 詳しくは、「COPY ステートメントを使用して直接コピーする」をご覧ください。
• ソース データ ストアと形式が、本来は COPY ステートメントでサポートされていない形式の場合は、代わりに COPY ステートメントを使用したステージング コピーを使います。 ステージング コピー機能はスループットも優れています。 データを COPY ステートメントと互換性のある形式に自動的に変換し、データを blob storage Azure格納してから、COPY ステートメントを呼び出してデータをAzure Synapse Analyticsに読み込みます。

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 サービス エンドポイントで構成されている場合は、ストレージ アカウントで "信頼された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 ステートメント設定がサポートされています。

"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 Blob Storage リンク サービスまたはAzure Data Lake Storage Gen2 リンク サービスを作成し、アカウント キーまたはシステム マネージド ID 認証を使用して、Azure ストレージ アカウントを中間ストレージとして参照します。

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

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

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

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

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

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

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

   重要

   • ストレージのリンクされたサービスにマネージド ID 認証を使用する場合は、それぞれ Azure BLOB と Azure Data Lake Storage Gen2 に必要な構成について学習します。
   • Azure Storageが VNet サービス エンドポイントで構成されている場合は、ストレージ アカウントで "信頼された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 は指定されません。

"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 Blob StorageリンクサービスまたはAzure Data Lake Storage Gen2リンクサービスをアカウントキーまたはマネージドID認証で作成し、Azureストレージアカウントを一時ストレージとして参照します。

"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 Decimal 列に読み込まれる空の値が含まれている場合は、次のエラーが発生する可能性があります。

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 プロパティを指定する方法の例です。 スキーマとテーブル名の複数の組み合わせを示します。

次のエラーが表示される場合は、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 認証を使用していて、Azure Synapse ワークスペースのマネージド 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 ソースを使用して data フロー アクティビティを実行すると、ステージング場所ストレージ アカウントの入力を求めるメッセージが表示され、ステージング データの読み込みに使用されます。 これは、Azure Synapse Analyticsからデータを読み込むための最速のメカニズムです。

• ストレージのリンクされたサービスにマネージド ID 認証を使用する場合は、それぞれ Azure BLOB と Azure Data Lake Storage Gen2 に必要な構成について学習します。
• Azure Storageが VNet サービス エンドポイントで構成されている場合は、ストレージ アカウントで "信頼されたMicrosoft サービスを許可する" が有効になっているマネージド ID 認証を使用する必要があります。 Azure storage で VNet サービス エンドポイントを使用する場合の詳細を参照してください。
• ソースとして Azure Synapse serverless SQL プールを使用する場合、ステージングの有効化はサポートされていません。

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

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

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

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

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

シンク変換

Azure Synapse Analyticsに固有の設定は、シンク変換の Settings タブで使用できます。

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

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

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

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

• ストレージのリンクされたサービスにマネージド ID 認証を使用する場合は、それぞれ Azure BLOB と Azure Data Lake Storage Gen2 に必要な構成について学習します。
• Azure Storageが VNet サービス エンドポイントで構成されている場合は、ストレージ アカウントで "信頼されたMicrosoft サービスを許可する" が有効になっているマネージド ID 認証を使用する必要があります。 Azure storage で VNet サービス エンドポイントを使用する場合の詳細を参照してください。

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

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

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

エラー行の処理

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

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

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

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

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

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

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 のバージョンをアップグレードするには、リンクされたサービスの編集ページでRecommendedを選択し、Versionの下に配置し、推奨バージョンのリンク サービス プロパティを参照してリンク サービスを構成してください。

推奨バージョンとレガシ バージョンの違い

次の表は、推奨バージョンとレガシ バージョンを使用したAzure Synapse Analyticsの違いを示しています。

関連コンテンツ

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