Azure Data Factory を使用して Azure SQL Data Warehouse のデータをコピーおよび変換するCopy and transform data in Azure SQL Data Warehouse by using Azure Data Factory

この記事では、Azure Data Factory のコピー アクティビティを使用して、Azure SQL Data Warehouse との間でデータをコピーし、Data Flow を使用して Azure Data Lake Storage Gen2 でデータを変換する方法について説明します。This article outlines how to use Copy Activity in Azure Data Factory to copy data from and to Azure SQL Data Warehouse, and use Data Flow to transform data in Azure Data Lake Storage Gen2. Azure Data Factory については、入門記事でをご覧ください。To learn about Azure Data Factory, read the introductory article.

サポートされる機能Supported capabilities

この Azure SQL Data Warehouse コネクタは、次のアクティビティでサポートされます。This Azure SQL Data Warehouse connector is supported for the following activities:

コピー アクティビティについて、この Azure SQL Data Warehouse コネクタはこれらの機能をサポートします。For Copy activity, this Azure SQL Data Warehouse connector supports these functions:

  • SQL 認証を使って、およびサービス プリンシパルまたは Azure リソースのマネージド ID で Azure Active Directory (Azure AD) アプリケーション トークン認証を使って、データをコピーする。Copy data by using SQL authentication and Azure Active Directory (Azure AD) Application token authentication with a service principal or managed identities for Azure resources.
  • ソースとして、SQL クエリまたはストアド プロシージャを使用してデータを取得する。As a source, retrieve data by using a SQL query or stored procedure.
  • シンクとして、PolyBase または一括挿入を使用してデータを読み込む。As a sink, load data by using PolyBase or a bulk insert. コピーのパフォーマンスがよいので、PolyBase をお勧めします。We recommend PolyBase for better copy performance.

重要

Azure Data Factory Integration Runtime を使ってデータをコピーする場合は、Azure サービスがサーバーにアクセスできるように Azure SQL Server ファイアウォールを構成します。If you copy data by using Azure Data Factory Integration Runtime, configure an Azure SQL server firewall so that Azure services can access the server. セルフホステッド統合ランタイムを使用してデータをコピーする場合は、適切な IP 範囲を許可するように Azure SQL Server ファイアウォールを構成します。If you copy data by using a self-hosted integration runtime, configure the Azure SQL server firewall to allow the appropriate IP range. この範囲には、Azure SQL Database への接続に使用されるコンピューターの IP アドレスが含まれています。This range includes the machine's IP that is used to connect to Azure SQL Database.

作業開始Get started

ヒント

最高のパフォーマンスを実現するには、PolyBase を使用して、Azure SQL Data Warehouse にデータを読み込みます。To achieve best performance, use PolyBase to load data into Azure SQL Data Warehouse. PolyBase を使用して Azure SQL Data Warehouse にデータを読み込む 」セクションに詳細が記載されています。The Use PolyBase to load data into Azure SQL Data Warehouse section has details. ユース ケースを使用したチュートリアルについては、1 TB のデータを Azure Data Factory を使用して 15 分以内に Azure SQL Data Warehouse に読み込む方法に関するページを参照してください。For a walkthrough with a use case, see Load 1 TB into Azure SQL Data Warehouse under 15 minutes with Azure Data Factory.

次のいずれかのツールまたは SDK を使用して、パイプラインでコピー アクティビティを使用できます。You can use one of the following tools or SDKs to use the copy activity with a pipeline. 詳細な手順については、以下のリンクを選択してください。Select a link for step-by-step instructions:

以下のセクションでは、Azure SQL Data Warehouse コネクタに固有の Data Factory エンティティを定義するプロパティの詳細を説明します。The following sections provide details about properties that define Data Factory entities specific to an Azure SQL Data Warehouse connector.

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

Azure SQL Data Warehouse のリンクされたサービスでは、次のプロパティがサポートされます。The following properties are supported for an Azure SQL Data Warehouse linked service:

プロパティProperty 説明Description 必須Required
typetype type プロパティは AzureSqlDW に設定する必要があります。The type property must be set to AzureSqlDW. はいYes
connectionStringconnectionString connectionString プロパティには、Azure SQL Data Warehouse インスタンスに接続するために必要な情報を指定します。Specify the information needed to connect to the Azure SQL Data Warehouse instance for the connectionString property.
Data Factory に安全に格納するには、このフィールドを SecureString として指定します。Mark this field as a SecureString to store it securely in Data Factory. パスワード/サービス プリンシパル キーを Azure Key Vault に格納して、それが SQL 認証の場合は接続文字列から password 構成をプルすることもできます。You can also put password/service principal key in Azure Key Vault,and if it's SQL authentication pull the password configuration out of the connection string. 詳しくは、表の下の JSON の例と、「Azure Key Vault への資格情報の格納」の記事をご覧ください。See the JSON example below the table and Store credentials in Azure Key Vault article with more details.
はいYes
servicePrincipalIdservicePrincipalId アプリケーションのクライアント ID を取得します。Specify the application's client ID. サービス プリンシパルで Azure AD 認証を使う場合は、はい。Yes, when you use Azure AD authentication with a service principal.
servicePrincipalKeyservicePrincipalKey アプリケーションのキーを取得します。Specify the application's key. このフィールドを SecureString としてマークして Data Factory に安全に保管するか、Azure Key Vault に格納されているシークレットを参照します。Mark this field as a SecureString to store it securely in Data Factory, or reference a secret stored in Azure Key Vault. サービス プリンシパルで Azure AD 認証を使う場合は、はい。Yes, when you use Azure AD authentication with a service principal.
tenanttenant アプリケーションが存在するテナントの情報 (ドメイン名またはテナント ID) を指定します。Specify the tenant information (domain name or tenant ID) under which your application resides. Azure Portal の右上隅にマウスを置くことで取得できます。You can retrieve it by hovering the mouse in the top-right corner of the Azure portal. サービス プリンシパルで Azure AD 認証を使う場合は、はい。Yes, when you use Azure AD authentication with a service principal.
connectViaconnectVia データ ストアに接続するために使用される統合ランタイムThe integration runtime to be used to connect to the data store. Azure Integration Runtime またはセルフホステッド統合ランタイムを使用できます (データ ストアがプライベート ネットワークにある場合)。You can use Azure Integration Runtime or a self-hosted integration runtime (if your data store is located in a private network). 指定されていない場合は、既定の Azure 統合ランタイムが使用されます。If not specified, it uses the default Azure Integration Runtime. いいえNo

さまざまな認証の種類の前提条件と JSON サンプルについては、以下のセクションをご覧ください。For different authentication types, refer to the following sections on prerequisites and JSON samples, respectively:

ヒント

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

SQL 認証SQL authentication

SQL 認証を使用するリンクされたサービスの例Linked service example that uses SQL authentication

{
    "name": "AzureSqlDWLinkedService",
    "properties": {
        "type": "AzureSqlDW",
        "typeProperties": {
            "connectionString": {
                "type": "SecureString",
                "value": "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 内のパスワード:Password in Azure Key Vault:

{
    "name": "AzureSqlDWLinkedService",
    "properties": {
        "type": "AzureSqlDW",
        "typeProperties": {
            "connectionString": {
                "type": "SecureString",
                "value": "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"
        }
    }
}

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

サービス プリンシパル ベースの Azure AD アプリケーション トークン認証を使うには、以下の手順のようにします。To use service principal-based Azure AD application token authentication, follow these steps:

  1. Azure portal から Azure Active Directory アプリケーションを作成しますCreate an Azure Active Directory application from the Azure portal. アプリケーション名と、リンクされたサービスを定義する次の値を記録しておきます。Make note of the application name and the following values that define the linked service:

    • アプリケーション IDApplication ID
    • アプリケーション キーApplication key
    • テナント IDTenant ID
  2. まだ行っていない場合は、Azure portal で Azure SQL Server の Azure Active Directory 管理者をプロビジョニングしますProvision an Azure Active Directory administrator for your Azure SQL server on the Azure portal if you haven't already done so. Azure AD 管理者には、Azure AD ユーザーまたは Azure AD グループを使用できます。The Azure AD administrator can be an Azure AD user or Azure AD group. マネージド ID を含むグループに管理者ロールを付与する場合は、手順 3. と手順 4. をスキップします。If you grant the group with managed identity an admin role, skip steps 3 and 4. 管理者には、データベースへのフル アクセスがあります。The administrator will have full access to the database.

  3. サービス プリンシパルの 包含データベース ユーザーを作成しますCreate contained database users for the service principal. SSMS のようなツールと、少なくとも ALTER ANY USER アクセス許可を持つ Azure AD ID を使用して、データをコピーするデータ ウェアハウスに接続します。Connect to the data warehouse from or to which you want to copy data by using tools like SSMS, with an Azure AD identity that has at least ALTER ANY USER permission. 次の T-SQL を実行します。Run the following T-SQL:

    CREATE USER [your application name] FROM EXTERNAL PROVIDER;
    
  4. SQL ユーザーや他のユーザーに対する通常の方法で、サービス プリンシパルに必要なアクセス許可を付与します。Grant the service principal needed permissions as you normally do for SQL users or others. 次のコードを実行するか、こちらでその他のオプションを参照してください。Run the following code, or refer to more options here. PolyBase を使用してデータを読み込む場合は、必要なデータベース アクセス許可について学習します。If you want to use PolyBase to load the data, learn the required database permission.

    EXEC sp_addrolemember db_owner, [your application name];
    
  5. Azure Data Factory で、Azure SQL Data Warehouse のリンクされたサービスを構成しますConfigure an Azure SQL Data Warehouse linked service in Azure Data Factory.

サービス プリンシパル認証を使うリンクされたサービスの例Linked service example that uses service principal authentication

{
    "name": "AzureSqlDWLinkedService",
    "properties": {
        "type": "AzureSqlDW",
        "typeProperties": {
            "connectionString": {
                "type": "SecureString",
                "value": "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 認証Managed identities for Azure resources authentication

データ ファクトリは、特定のファクトリを表す Azure リソースのマネージド ID に関連付けることができます。A data factory can be associated with a managed identity for Azure resources that represents the specific factory. このマネージド ID を Azure SQL Data Warehouse 認証に使用できます。You can use this managed identity for Azure SQL Data Warehouse authentication. 指定されたファクトリは、この ID を使用してデータ ウェアハウスにアクセスし、データを双方向にコピーできます。The designated factory can access and copy data from or to your data warehouse by using this identity.

マネージド ID 認証を使用するには、次の手順に従います。To use managed identity authentication, follow these steps:

  1. まだ行っていない場合は、Azure portal で Azure SQL Server の Azure Active Directory 管理者をプロビジョニングしますProvision an Azure Active Directory administrator for your Azure SQL server on the Azure portal if you haven't already done so. Azure AD 管理者には、Azure AD ユーザーまたは Azure AD グループを使用できます。The Azure AD administrator can be an Azure AD user or Azure AD group. マネージド ID を含むグループに管理者ロールを付与する場合は、手順 3. と手順 4. をスキップします。If you grant the group with managed identity an admin role, skip steps 3 and 4. 管理者には、データベースへのフル アクセスがあります。The administrator will have full access to the database.

  2. Data Factory のマネージド ID の 包含データベース ユーザー を作成します。Create contained database users for the Data Factory Managed Identity. SSMS のようなツールと、少なくとも ALTER ANY USER アクセス許可を持つ Azure AD ID を使用して、データをコピーするデータ ウェアハウスに接続します。Connect to the data warehouse from or to which you want to copy data by using tools like SSMS, with an Azure AD identity that has at least ALTER ANY USER permission. 次の T-SQL を実行します。Run the following T-SQL.

    CREATE USER [your Data Factory name] FROM EXTERNAL PROVIDER;
    
  3. SQL ユーザーや他のユーザーに対する通常の方法と同様に、Data Factory のマネージド ID に必要なアクセス許可を付与しますGrant the Data Factory Managed Identity needed permissions as you normally do for SQL users and others. 次のコードを実行するか、こちらでその他のオプションを参照してください。Run the following code, or refer to more options here. PolyBase を使用してデータを読み込む場合は、必要なデータベース アクセス許可について学習します。If you want to use PolyBase to load the data, learn the required database permission.

    EXEC sp_addrolemember db_owner, [your Data Factory name];
    
  4. Azure Data Factory で、Azure SQL Data Warehouse のリンクされたサービスを構成しますConfigure an Azure SQL Data Warehouse linked service in Azure Data Factory.

例:Example:

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

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

データセットを定義するために使用できるセクションとプロパティの完全な一覧については、データセットに関する記事をご覧ください。For a full list of sections and properties available for defining datasets, see the Datasets article.

Azure SQL Data Warehouse データセットでは、次のプロパティがサポートされます。The following properties are supported for Azure SQL Data Warehouse dataset:

プロパティProperty 説明Description 必須Required
typetype データセットの type プロパティは、AzureSqlDWTable を設定する必要があります。The type property of the dataset must be set to AzureSqlDWTable. はいYes
schemaschema スキーマの名前。Name of the schema. ソースの場合はいいえ、シンクの場合ははいNo for source, Yes for sink
tabletable テーブル/ビューの名前。Name of the table/view. ソースの場合はいいえ、シンクの場合ははいNo for source, Yes for sink
tableNametableName スキーマがあるテーブル/ビューの名前。Name of the table/view with schema. このプロパティは下位互換性のためにサポートされています。This property is supported for backward compatibility. 新しいワークロードでは、schematable を使用します。For new workload, use schema and table. ソースの場合はいいえ、シンクの場合ははいNo for source, Yes for sink

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

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

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

アクティビティの定義に利用できるセクションとプロパティの完全な一覧については、パイプラインに関する記事を参照してください。For a full list of sections and properties available for defining activities, see the Pipelines article. このセクションでは、Azure SQL Data Warehouse のソースとシンクでサポートされるプロパティの一覧を示します。This section provides a list of properties supported by the Azure SQL Data Warehouse source and sink.

ソースとしての Azure SQL Data WarehouseAzure SQL Data Warehouse as the source

Azure SQL Data Warehouse からデータをコピーする場合は、コピー アクティビティのソースで type プロパティを SqlDWSource に設定します。To copy data from Azure SQL Data Warehouse, set the type property in the Copy Activity source to SqlDWSource. コピー アクティビティの source セクションでは、次のプロパティがサポートされます。The following properties are supported in the Copy Activity source section:

プロパティProperty 説明Description 必須Required
typetype コピー アクティビティのソースの type プロパティは SqlDWSource に設定する必要があります。The type property of the Copy Activity source must be set to SqlDWSource. はいYes
sqlReaderQuerysqlReaderQuery カスタム SQL クエリを使用してデータを読み取ります。Use the custom SQL query to read data. 例: select * from MyTable.Example: select * from MyTable. いいえNo
sqlReaderStoredProcedureNamesqlReaderStoredProcedureName ソース テーブルからデータを読み取るストアド プロシージャの名前。The name of the stored procedure that reads data from the source table. 最後の SQL ステートメントはストアド プロシージャの SELECT ステートメントにする必要があります。The last SQL statement must be a SELECT statement in the stored procedure. いいえNo
storedProcedureParametersstoredProcedureParameters ストアド プロシージャのパラメーター。Parameters for the stored procedure.
使用可能な値は、名前または値のペアです。Allowed values are name or value pairs. パラメーターの名前とその大文字と小文字は、ストアド プロシージャのパラメーターの名前とその大文字小文字と一致する必要があります。Names and casing of parameters must match the names and casing of the stored procedure parameters.
いいえNo

注意する点Points to note

  • SqlSourcesqlReaderQuery が指定されている場合、コピー アクティビティは、Azure SQL Data Warehouse ソースに対してこのクエリを実行してデータを取得します。If the sqlReaderQuery is specified for the SqlSource, the Copy Activity runs this query against the Azure SQL Data Warehouse source to get the data. または、ストアド プロシージャを指定できます。Or you can specify a stored procedure. ストアド プロシージャがパラメーターを受け取る場合は、sqlReaderStoredProcedureNamestoredProcedureParameters を指定します。Specify the sqlReaderStoredProcedureName and storedProcedureParameters if the stored procedure takes parameters.
  • sqlReaderQuery または sqlReaderStoredProcedureName を指定しない場合は、データセット JSON の structure セクションで定義されている列を使用して、クエリが作成されます。If you don't specify either sqlReaderQuery or sqlReaderStoredProcedureName, the columns defined in the structure section of the dataset JSON are used to construct a query. select column1, column2 from mytable が Azure SQL Data Warehouse に対して実行されます。select column1, column2 from mytable runs against Azure SQL Data Warehouse. データセット定義に structure がない場合は、すべての列がテーブルから選択されます。If the dataset definition doesn't have the structure, all columns are selected from the table.

SQL クエリの例SQL query example

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

ストアド プロシージャの例Stored procedure example

"activities":[
    {
        "name": "CopyFromAzureSQLDW",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<Azure SQL DW 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>"
            }
        }
    }
]

ストアド プロシージャの定義Stored procedure definition

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 SQL Data WarehouseAzure SQL Data Warehouse as sink

Azure SQL Data Warehouse にデータをコピーする場合は、コピー アクティビティのシンクの種類を SqlDWSink に設定します。To copy data to Azure SQL Data Warehouse, set the sink type in Copy Activity to SqlDWSink. コピー アクティビティの sink セクションでは、次のプロパティがサポートされます。The following properties are supported in the Copy Activity sink section:

プロパティProperty 説明Description 必須Required
typetype コピー アクティビティのシンクの type プロパティは、SqlDWSink に設定する必要があります。The type property of the Copy Activity sink must be set to SqlDWSink. はいYes
allowPolyBaseallowPolyBase BULKINSERT メカニズムではなく PolyBase (該当する場合) を使用するかどうかを示します。Indicates whether to use PolyBase, when applicable, instead of the BULKINSERT mechanism.

SQL Data Warehouse へのデータの読み込みには、PolyBase を使うことをお勧めします。We recommend that you load data into SQL Data Warehouse by using PolyBase. 制約と詳細については、「PolyBase を使用して Azure SQL Data Warehouse にデータを読み込む」をご覧ください。See the Use PolyBase to load data into Azure SQL Data Warehouse section for constraints and details.

使用可能な値: True、および False (既定値)。Allowed values are True and False (default).
いいえNo
polyBaseSettingspolyBaseSettings allowPolybase プロパティが true に設定されているときに指定できるプロパティのグループ。A group of properties that can be specified when the allowPolybase property is set to true. いいえNo
rejectValuerejectValue クエリが失敗するまでに拒否できる行の数または割合を指定します。Specifies the number or percentage of rows that can be rejected before the query fails.

PolyBase の拒否オプションについて詳しくは、「CREATE EXTERNAL TABLE (Transact-SQL)」の「引数」セクションをご覧ください。Learn more about PolyBase’s reject options in the Arguments section of CREATE EXTERNAL TABLE (Transact-SQL).

使用可能な値は、0 (既定値)、1、2 などです。Allowed values are 0 (default), 1, 2, etc.
いいえNo
rejectTyperejectType rejectValue オプションがリテラル値か割合かを指定します。Specifies whether the rejectValue option is a literal value or a percentage.

使用可能な値は、Value (既定値) と Percentage です。Allowed values are Value (default) and Percentage.
いいえNo
rejectSampleValuerejectSampleValue 拒否された行の割合が PolyBase で再計算されるまでに取得する行数を決定します。Determines the number of rows to retrieve before PolyBase recalculates the percentage of rejected rows.

使用可能な値は、1、2 などです。Allowed values are 1, 2, etc.
はい (rejectTypepercentage の場合)。Yes, if the rejectType is percentage.
useTypeDefaultuseTypeDefault PolyBase がテキスト ファイルからデータを取得する場合にどのように区切りテキスト ファイル内の不足値を処理するかを、指定します。Specifies how to handle missing values in delimited text files when PolyBase retrieves data from the text file.

このプロパティの詳細については、CREATE EXTERNAL FILE FORMAT (Transact-SQL) Arguments セクションをご覧ください。Learn more about this property from the Arguments section in CREATE EXTERNAL FILE FORMAT (Transact-SQL).

使用可能な値: True、および False (既定値)。Allowed values are True and False (default).

いいえNo
writeBatchSizewriteBatchSize SQL テーブルに挿入するバッチあたりの行数。Number of rows to inserts into the SQL table per batch. PolyBase が使われていない場合にのみ適用されます。Applies only when PolyBase isn't used.

使用可能な値は integer (行数) です。The allowed value is integer (number of rows). 既定では、Data Factory により行のサイズに基づいて適切なバッチ サイズが動的に決定されます。By default, Data Factory dynamically determines the appropriate batch size based on the row size.
いいえNo
writeBatchTimeoutwriteBatchTimeout タイムアウトする前に一括挿入操作の完了を待つ時間です。PolyBase が使われていない場合にのみ適用されます。Wait time for the batch insert operation to finish before it times out. Applies only when PolyBase isn't used.

使用可能な値は timespan です。The allowed value is timespan. 例:"00:30:00" (30 分)。Example: “00:30:00” (30 minutes).
いいえNo
preCopyScriptpreCopyScript コピー アクティビティの毎回の実行で、データを Azure SQL Data Warehouse に書き込む前に実行する SQL クエリを指定します。Specify a SQL query for Copy Activity to run before writing data into Azure SQL Data Warehouse in each run. 前に読み込まれたデータをクリーンアップするには、このプロパティを使います。Use this property to clean up the preloaded data. いいえNo
tableOptiontableOption ソースのスキーマに基づいて、シンク テーブルが存在しない場合に自動的にシンク テーブルを作成するかどうかを指定します。Specifies whether to automatically create the sink table if not exists based on the source schema. コピー アクティビティでステージング コピーが構成されている場合、テーブルの自動作成はサポートされません。Auto table creation is not supported when staged copy is configured in copy activity. 使用できる値は none (既定値)、autoCreate です。Allowed values are: none (default), autoCreate. いいえNo
disableMetricsCollectiondisableMetricsCollection Data Factory では、コピーのパフォーマンスの最適化とレコメンデーションのために、SQL Data Warehouse DWU などのメトリックが収集されます。Data Factory collects metrics such as SQL Data Warehouse DWUs for copy performance optimization and recommendations. この動作に不安がある場合は、true を指定してオフにします。If you are concerned with this behavior, specify true to turn it off. いいえ (既定値は false)No (default is false)

SQL Data Warehouse のシンクの例SQL Data Warehouse sink example

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

次のセクションでは、PolyBase を使用して SQL Data Warehouse への読み込みを効率的に実行する方法について詳しく説明します。Learn more about how to use PolyBase to efficiently load SQL Data Warehouse in the next section.

PolyBase を使用して Azure SQL Data Warehouse にデータを読み込むUse PolyBase to load data into Azure SQL Data Warehouse

PolyBase を使用すると、高いスループットで Azure SQL Data Warehouse に大量のデータを効率的に読み込むことができます。Using PolyBase is an efficient way to load a large amount of data into Azure SQL Data Warehouse with high throughput. 既定の BULKINSERT メカニズムではなく PolyBase を使用することで、スループットが大幅に向上することがわかります。You'll see a large gain in the throughput by using PolyBase instead of the default BULKINSERT mechanism. ユース ケースを使用したチュートリアルについては、1 TB のデータを Azure SQL Data Warehouse に読み込む方法に関するページをご覧ください。For a walkthrough with a use case, see Load 1 TB into Azure SQL Data Warehouse.

  • ソース データが Azure Blob、Azure Data Lake Storage Gen1、または Azure Data Lake Storage Gen2 内にあるときに、形式が PolyBase 互換の場合は、PolyBase を直接呼び出して、Azure SQL Data Warehouse でソースからデータを引き出すことができます。If your source data is in Azure Blob, Azure Data Lake Storage Gen1 or Azure Data Lake Storage Gen2, and the format is PolyBase compatible, you can use copy activity to directly invoke PolyBase to let Azure SQL Data Warehouse pull the data from source. 詳しくは、「 PolyBase を使用して直接コピーする 」をご覧ください。For details, see Direct copy by using PolyBase.
  • ソース データのストアと形式が、本来は PolyBase でサポートされていない形式の場合は、代わりに PolyBase を使用したステージング コピー を使います。If your source data store and format isn't originally supported by PolyBase, use the Staged copy by using PolyBase feature instead. ステージング コピー機能はスループットも優れています。The staged copy feature also provides you better throughput. PolyBase と互換性のある形式にデータを自動的に変換します。It automatically converts the data into PolyBase-compatible format. そして、Azure BLOB ストレージにデータを格納します。And it stores the data in Azure Blob storage. その後、データは SQL Data Warehouse に読み込まれます。It then loads the data into SQL Data Warehouse.

PolyBase を使用して直接コピーするDirect copy by using PolyBase

SQL Data Warehouse の PolyBase では、Azure Blob、Azure Data Lake Storage Gen1、および Azure Data Lake Storage Gen2 が直接サポートされます。SQL Data Warehouse PolyBase directly supports Azure Blob, Azure Data Lake Storage Gen1 and Azure Data Lake Storage Gen2. ソース データがこのセクションで説明する条件を満たしている場合は、PolyBase を使用してソース データ ストアから Azure SQL Data Warehouse に直接コピーします。If your source data meets the criteria described in this section, use PolyBase to copy directly from the source data store to Azure SQL Data Warehouse. それ以外の場合は、PolyBase を使用したステージング コピーを使います。Otherwise, use Staged copy by using PolyBase.

ヒント

データを効率的に SQL Data Warehouse にコピーするには、「Azure Data Factory makes it even easier and convenient to uncover insights from data when using Data Lake Store with SQL Data Warehouse」(Azure Data Factory を利用すれば、SQL Data Warehouse と共に Data Lake Store を使用する場合にデータからさらに容易かつ便利に情報を引き出せるようになる) を参考にしてください。To copy data efficiently to SQL Data Warehouse, learn more from Azure Data Factory makes it even easier and convenient to uncover insights from data when using Data Lake Store with SQL Data Warehouse.

要件が満たされない場合は、Azure Data Factory が設定を確認し、データ移動には自動的に BULKINSERT メカニズムが使用されるように戻ります。If the requirements aren't met, Azure Data Factory checks the settings and automatically falls back to the BULKINSERT mechanism for the data movement.

  1. ソース リンク サービスでは、次の種類と認証方法が使用されます。The source linked service is with the following types and authentication methods:

    サポートされるソース データ ストアの種類Supported source data store type サポートされる認証の種類Supported source authentication type
    Azure BLOBAzure Blob アカウント キー認証、マネージド ID 認証Account key authentication, managed identity authentication
    Azure Data Lake Storage Gen1Azure Data Lake Storage Gen1 サービス プリンシパルの認証Service principal authentication
    Azure Data Lake Storage Gen2Azure Data Lake Storage Gen2 アカウント キー認証、マネージド ID 認証Account key authentication, managed identity authentication

    重要

    VNet サービス エンドポイントを使用して Azure Storage が構成されている場合は、マネージド ID 認証を使用する必要があります。「Azure Storage で VNet サービス エンドポイントを使用した場合の影響」を参照してください。If your Azure Storage is configured with VNet service endpoint, you must use managed identity authentication - refer to Impact of using VNet Service Endpoints with Azure storage. Data Factory で必要な構成については、Azure Blob のマネージド ID 認証Azure Data Lake Storage Gen2 のマネージド ID 認証のセクションをそれぞれ参照してください。Learn the required configurations in Data Factory from Azure Blob - managed identity authentication and Azure Data Lake Storage Gen2 - managed identity authentication section respectively.

  2. ソース データ形式は、次のように構成された ParquetORC、または区切りテキストです。The source data format is of Parquet, ORC, or Delimited text, with the following configurations:

    1. フォルダーのパスにワイルドカード フィルターが含まれない。Folder path doesn't contain wildcard filter.
    2. ファイル名が空か、1 つのファイルを指している。File name is empty, or points to a single file. コピー アクティビティでワイルドカードのファイル名を指定する場合は、* または *.* のみを指定できます。If you specify wildcard file name in copy activity, it can only be * or *.*.
    3. rowDelimiterdefault\n\r\n、または \r である。rowDelimiter is default, \n, \r\n, or \r.
    4. nullValue が既定値のままか、空の文字列 ("") に設定されており、treatEmptyAsNull が既定値のままか、true に設定されている。nullValue is left as default or set to empty string (""), and treatEmptyAsNull is left as default or set to true.
    5. encodingName が既定値のままか、utf-8 に設定されている。encodingName is left as default or set to utf-8.
    6. quoteCharescapeChar、および skipLineCount が指定されていない。quoteChar, escapeChar, and skipLineCount aren't specified. PolyBase では、ヘッダー行のスキップがサポートされます。これは、ADF で firstRowAsHeader として構成できます。PolyBase support skip header row, which can be configured as firstRowAsHeader in ADF.
    7. compression圧縮なしGZip、または Deflateである。compression can be no compression, GZip, or Deflate.
  3. ソースがフォルダーの場合は、コピー アクティビティの recursive を true に設定する必要があります。If your source is a folder, recursive in copy activity must be set to true.

注意

ソースがフォルダーの場合、PolyBase ではフォルダーとそのすべてのサブフォルダーからファイルが取得され、ファイル名の先頭に下線 () またはピリオド (.) が付いているファイルからはデータが取得されないことに注意してください。詳細については、LOCATION 引数に関するこちらのドキュメントを参照してください。If your source is a folder, note PolyBase retrieves files from the folder and all of its subfolders, and it doesn't retrieve data from files for which the file name begins with an underline () or a period (.), as documented here - LOCATION argument.

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

PolyBase を使用したステージング コピーStaged copy by using PolyBase

ソース データが前のセクションの条件を満たしていない場合は、中間ステージング Azure BLOB ストレージ インスタンス経由でのデータのコピーを有効にします。When your source data doesn’t meet the criteria in the previous section, enable data copying via an interim staging Azure Blob storage instance. Azure Premium Storage は使用できません。It can't be Azure Premium Storage. その場合、Azure Data Factory は、PolyBase のデータ形式要件を満たすように、データの変換を自動的に実行します。In this case, Azure Data Factory automatically runs transformations on the data to meet the data format requirements of PolyBase. その後、PolyBase を使用してデータを SQL Data Warehouse に読み込みます。Then it uses PolyBase to load data into SQL Data Warehouse. 最後に、BLOB ストレージから一時データをクリーンアップします。Finally, it cleans up your temporary data from the blob storage. ステージング Azure BLOB ストレージ インスタンス経由でのデータのコピーについて詳しくは、「ステージング コピー」をご覧ください。See Staged copy for details about copying data via a staging Azure Blob storage instance.

この機能を使うには、中間 BLOB ストレージを含む Azure Storage アカウントを参照する Azure Blob Storage のリンクされたサービスを作成します。To use this feature, create an Azure Blob Storage linked service that refers to the Azure storage account with the interim blob storage. その後、次のコードで示すように、コピー アクティビティの enableStaging プロパティと stagingSettings プロパティを指定します。Then specify the enableStaging and stagingSettings properties for the Copy Activity as shown in the following code.

重要

VNet サービス エンドポイントを使用してステージング Azure Storage が構成されている場合は、マネージド ID 認証を使用する必要があります。「Azure Storage で VNet サービス エンドポイントを使用した場合の影響」を参照してください。If your staging Azure Storage is configured with VNet service endpoint, you must use managed identity authentication - refer to Impact of using VNet Service Endpoints with Azure storage. Data Factory に必要な構成については、Azure Blob のマネージド ID 認証に関するセクションを参照してください。Learn the required configurations in Data Factory from Azure Blob - managed identity authentication.

"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": "MyStagingBlob",
                    "type": "LinkedServiceReference"
                }
            }
        }
    }
]

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

次のセクションでは、「Azure SQL Data Warehouse のベスト プラクティス」に記載されているもの以外のベスト プラクティスを説明します。The following sections provide best practices in addition to those mentioned in Best practices for Azure SQL Data Warehouse.

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

PolyBase を使うには、データを SQL Data Warehouse に読み込むユーザーが、ターゲット データベースでの "CONTROL" アクセス許可を持っている必要があります。To use PolyBase, the user that loads data into SQL Data Warehouse must have "CONTROL" permission on the target database. これを実現する方法の 1 つは、ユーザーを db_owner ロールのメンバーとして追加することです。One way to achieve that is to add the user as a member of the db_owner role. 方法については、SQL Data Warehouse の概要に関するページをご覧ください。Learn how to do that in the SQL Data Warehouse overview.

行のサイズとデータ型の制限Row size and data type limits

PolyBase の読み込みは、1 MB 未満の行に制限されます。PolyBase loads are limited to rows smaller than 1 MB. VARCHR(MAX)、NVARCHAR(MAX)、VARBINARY(MAX) への読み込みには使用できません。It cannot be used to load to VARCHR(MAX), NVARCHAR(MAX), or VARBINARY(MAX). 詳しくは、SQL Data Warehouse サービスの容量制限に関するページをご覧ください。For more information, see SQL Data Warehouse service capacity limits.

ソース データに 1 MB を超える行がある場合は、ソース テーブルを複数の小さいテーブルに垂直分割できます。When your source data has rows greater than 1 MB, you might want to vertically split the source tables into several small ones. 各行の最大サイズが制限を超えないことを確認します。Make sure that the largest size of each row doesn't exceed the limit. その後、この分割した小さいテーブルは、PolyBase を使用して Azure SQL Data Warehouse に読み込み、マージすることができます。The smaller tables can then be loaded by using PolyBase and merged together in Azure SQL Data Warehouse.

または、このように広い列を持つデータについては、[Allow polybase](PolyBase を許可する) 設定をオフにすることで、ADF を使用したデータの読み込みに PolyBase 以外を使用できます。Alternatively, for data with such wide columns, you can use non-PolyBase to load the data using ADF, by turning off "allow PolyBase" setting.

SQL Data Warehouse リソース クラスSQL Data Warehouse resource class

可能な限りスループットを最大化するには、PolyBase で SQL Data Warehouse にデータを読み込むユーザーに、より大きなリソース クラスを割り当てます。To achieve the best possible throughput, assign a larger resource class to the user that loads data into SQL Data Warehouse via PolyBase.

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

10 進数の列への読み込みLoading to Decimal column

ソース データがテキスト形式であるか、その他の (ステージング コピーおよび PolyBase を使用した) PolyBase 非互換ストアにあり、それに、SQL Data Warehouse の 10 進数の列に読み込まれる空の値が含まれている場合は、次のエラーが発生することがあります。If your source data is in text format or other non-PolyBase compatible stores (using staged copy and PolyBase), and it contains empty value to be loaded into SQL Data Warehouse Decimal column, you may hit the following error:

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

これを解決するには、コピー アクティビティの sink の PolyBase 設定で、(false として) "型の既定を使用する" オプションを選択解除します。The solution is to unselect "Use type default" option (as false) in copy activity sink -> PolyBase settings. "USE_TYPE_DEFAULT" は、PolyBase でテキスト ファイルからデータが取得される際に区切りテキスト ファイル内の欠落値を処理する方法を指定する PolyBase ネイティブ構成です。"USE_TYPE_DEFAULT" is a PolyBase native configuration, which specifies how to handle missing values in delimited text files when PolyBase retrieves data from the text file.

Azure SQL Data Warehouse の tableNametableName in Azure SQL Data Warehouse

次の表は、JSON データセットで tableName プロパティを指定する方法の例です。The following table gives examples of how to specify the tableName property in the JSON dataset. スキーマとテーブル名の複数の組み合わせを示します。It shows several combinations of schema and table names.

DB スキーマDB Schema テーブル名Table name tableName JSON プロパティtableName JSON property
dbodbo MyTableMyTable MyTable、dbo.MyTable、または [dbo].[MyTable]MyTable or dbo.MyTable or [dbo].[MyTable]
dbo1dbo1 MyTableMyTable dbo1.MyTable または [dbo1].[MyTable]dbo1.MyTable or [dbo1].[MyTable]
dbodbo My.TableMy.Table [My.Table] または [dbo].[My.Table][My.Table] or [dbo].[My.Table]
dbo1dbo1 My.TableMy.Table [dbo1].[My.Table][dbo1].[My.Table]

次のエラーが表示される場合は、tableName プロパティに指定した値に問題がある可能性があります。If you see the following error, the problem might be the value you specified for the tableName property. tableName JSON プロパティの値を指定する正しい方法については、上の表を参照してください。See the preceding table for the correct way to specify values for the tableName JSON property.

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

既定値を持つ列Columns with default values

現在、Data Factory の PolyBase 機能では、ターゲット テーブルと同じ数の列のみを使用できます。Currently, the PolyBase feature in Data Factory accepts only the same number of columns as in the target table. たとえば、4 つの列を含むテーブルがあり、その列の 1 つには既定値が定義されているものとします。An example is a table with four columns where one of them is defined with a default value. それでも入力データには 4 つの列が必要です。The input data still needs to have four columns. 入力データセットが 3 列の場合は、次のメッセージのようなエラーが発生します。A three-column input dataset yields an error similar to the following message:

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

null 値は、特殊な形式の既定値です。The NULL value is a special form of the default value. 列が null 許容の場合、その列に対する BLOB 内の入力データが空になる可能性があります。If the column is nullable, the input data in the blob for that column might be empty. ただし、入力データセットから欠落することはできません。But it can't be missing from the input dataset. PolyBase は、欠落している値に対して null を Azure SQL Data Warehouse に挿入します。PolyBase inserts NULL for missing values in Azure SQL Data Warehouse.

Mapping Data Flow のプロパティMapping data flow properties

Mapping Data Flow のソース変換シンク変換に関する記事で詳細を確認してください。Learn details from source transformation and sink transformation in mapping data flow.

Azure SQL Data Warehouse のデータ型のマッピングData type mapping for Azure SQL Data Warehouse

Azure SQL Data Warehouse をコピー元またはコピー先としてデータをコピーするとき、次の Azure SQL Data Warehouse のデータ型から Azure Data Factory の中間データ型へのマッピングが使用されます。When you copy data from or to Azure SQL Data Warehouse, the following mappings are used from Azure SQL Data Warehouse data types to Azure Data Factory interim data types. コピー アクティビティでソースのスキーマとデータ型がシンクにマッピングされるしくみについては、スキーマとデータ型のマッピングに関する記事を参照してください。See schema and data type mappings to learn how Copy Activity maps the source schema and data type to the sink.

ヒント

SQL DW でサポートされるデータ型と、サポートされていないものの対処法については、「Azure SQL Data Warehouse でのテーブルのデータ型」の記事を参照してください。Refer to Table data types in Azure SQL Data Warehouse article on SQL DW supported data types and the workarounds for unsupported ones.

Azure SQL Data Warehouse のデータ型Azure SQL Data Warehouse data type Data Factory の中間データ型Data Factory interim data type
bigintbigint Int64Int64
binarybinary Byte[]Byte[]
bitbit BooleanBoolean
charchar String, Char[]String, Char[]
datedate DatetimeDateTime
DatetimeDatetime DatetimeDateTime
datetime2datetime2 DatetimeDateTime
DatetimeoffsetDatetimeoffset DateTimeOffsetDateTimeOffset
DecimalDecimal DecimalDecimal
FILESTREAM attribute (varbinary(max))FILESTREAM attribute (varbinary(max)) Byte[]Byte[]
FloatFloat DoubleDouble
imageimage Byte[]Byte[]
intint Int32Int32
moneymoney DecimalDecimal
ncharnchar String, Char[]String, Char[]
numericnumeric DecimalDecimal
nvarcharnvarchar String, Char[]String, Char[]
realreal SingleSingle
rowversionrowversion Byte[]Byte[]
smalldatetimesmalldatetime DatetimeDateTime
smallintsmallint Int16Int16
smallmoneysmallmoney DecimalDecimal
timetime TimeSpanTimeSpan
tinyinttinyint ByteByte
uniqueidentifieruniqueidentifier GuidGuid
varbinaryvarbinary Byte[]Byte[]
varcharvarchar String, Char[]String, Char[]

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

プロパティの詳細については、Lookup アクティビティに関するページを参照してください。To learn details about the properties, check Lookup activity.

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

プロパティの詳細については、GetMetadata アクティビティに関するページを参照してください。To learn details about the properties, check GetMetadata activity

次の手順Next steps

Azure Data Factory のコピー アクティビティによってソースおよびシンクとしてサポートされるデータ ストアの一覧については、サポートされるデータ ストアと形式の表をご覧ください。For a list of data stores supported as sources and sinks by Copy Activity in Azure Data Factory, see supported data stores and formats.