Copiare dati da o in Azure SQL Data Warehouse usando Azure Data FactoryCopy data to or from Azure SQL Data Warehouse by using Azure Data Factory

Questo articolo illustra come usare l'attività di copia in Azure Data Factory per copiare dati da e in Azure SQL Data Warehouse.This article outlines how to use the Copy Activity in Azure Data Factory to copy data to and from an Azure SQL Data Warehouse. Si basa sull'articolo di panoramica dell'attività di copia che presenta una panoramica generale sull'attività di copia.It builds on the copy activity overview article that presents a general overview of copy activity.

Nota

Questo articolo si applica alla versione 2 del servizio Data Factory, attualmente in versione di anteprima. Se si usa la versione 1 del servizio Data Factory, disponibile a livello generale, vedere le informazioni sul connettore Azure SQL Data Warehouse nella versione 1.

Funzionalità supportateSupported capabilities

È possibile copiare dati da Azure SQL Data Warehouse in qualsiasi archivio dati di sink supportato o da qualsiasi archivio dati di origine supportato in Azure SQL Data Warehouse.You can copy data from/to Azure SQL Data Warehouse to any supported sink data store, or copy data from any supported source data store to Azure SQL Data Warehouse. Per un elenco degli archivi dati supportati come origini/sink dall'attività di copia, vedere la tabella relativa agli archivi dati supportati.For a list of data stores that are supported as sources/sinks by the copy activity, see the Supported data stores table.

In particolare, il connettore Azure SQL Data Warehouse supporta:Specifically, this Azure SQL Data Warehouse connector supports:

  • La copia di dati tramite l'autenticazione SQL e l'autenticazione token dell'applicazione di Azure Active Directory con entità servizio o identità del servizio gestito.Copying data using SQL authentication, and Azure Active Directory Application token authentication with Service Principal or Managed Service Identity (MSI).
  • Come origine, il recupero di dati tramite query SQL o stored procedure.As source, retrieving data using SQL query or stored procedure.
  • Come sink, il caricamento di dati tramite PolyBase o l'inserimento bulk.As sink, loading data using PolyBase or bulk insert. Per ottimizzare le prestazioni di copia, è consigliabile usare il primo metodo.The former is recommended for better copy performance.

Importante

Si noti che PolyBase supporta solo l'autenticazione SQL, non l'autenticazione Azure Active Directory.

Importante

Se si copiano i dati tramite il runtime di integrazione di Azure, configurare il firewall del server SQL di Azure per consentire ai servizi di Azure di accedere al server. Se si copiano i dati tramite il runtime di integrazione self-hosted, configurare il firewall del server SQL di Azure per consentire un intervallo di indirizzi IP appropriato, incluso l'indirizzo IP del computer usato per la connessione al database SQL di Azure.

IntroduzioneGetting started

È possibile creare una pipeline con l'attività di copia usando uno degli strumenti o degli SDK seguenti.You can create a pipeline with the copy activity by using one of the following tools or SDKs. Selezionare un collegamento per passare a un'esercitazione con istruzioni dettagliate per creare una pipeline con un'attività di copia.Select a link to go to a tutorial with step-by-step instructions to create a pipeline with a copy activity.

Le sezioni seguenti riportano le informazioni dettagliate sulle proprietà che vengono usate per definire entità di Data Factory specifiche per il connettore Azure SQL Data Warehouse.The following sections provide details about properties that are used to define Data Factory entities specific to Azure SQL Data Warehouse connector.

Proprietà del servizio collegatoLinked service properties

Per il servizio collegato di Azure SQL Data Warehouse sono supportate le proprietà seguenti:The following properties are supported for Azure SQL Data Warehouse linked service:

ProprietàProperty DESCRIZIONEDescription ObbligatoriaRequired
typetype La proprietà del tipo deve essere impostata su: AzureSqlDWThe type property must be set to: AzureSqlDW Yes
connectionStringconnectionString Specificare le informazioni necessarie per connettersi all'istanza di Azure SQL Data Warehouse per la proprietà connectionString.Specify information needed to connect to the Azure SQL Data Warehouse instance for the connectionString property. Contrassegnare questo campo come SecureString per archiviarlo in modo sicuro in Azure Data Factory oppure fare riferimento a un segreto archiviato in 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. Yes
servicePrincipalIdservicePrincipalId Specificare l'ID client dell'applicazione.Specify the application's client ID. Sì, quando si usa l'autenticazione AAD con entità servizio.Yes when using AAD authentication with Service Principal.
servicePrincipalKeyservicePrincipalKey Specificare la chiave dell'applicazione.Specify the application's key. Contrassegnare questo campo come SecureString per archiviarlo in modo sicuro in Azure Data Factory oppure fare riferimento a un segreto archiviato in 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. Sì, quando si usa l'autenticazione AAD con entità servizio.Yes when using AAD authentication with Service Principal.
tenanttenant Specificare le informazioni sul tenant (nome di dominio o ID tenant) in cui si trova l'applicazione.Specify the tenant information (domain name or tenant ID) under which your application resides. È possibile recuperarlo passando il cursore del mouse sull'angolo superiore destro del portale di Azure.You can retrieve it by hovering the mouse in the upper-right corner of the Azure portal. Sì, quando si usa l'autenticazione AAD con entità servizio.Yes when using AAD authentication with Service Principal.
connectViaconnectVia Il runtime di integrazione da usare per la connessione all'archivio dati.The Integration Runtime to be used to connect to the data store. È possibile usare il runtime di integrazione di Azure o il runtime di integrazione self-hosted (se l'archivio dati si trova in una rete privata).You can use Azure Integration Runtime or Self-hosted Integration Runtime (if your data store is located in private network). Se non specificato, viene usato il runtime di integrazione di Azure predefinito.If not specified, it uses the default Azure Integration Runtime. No No

Per altri tipi di autenticazione, fare riferimento alle sezioni seguenti relative, rispettivamente, ai prerequisiti e agli esempi JSON:For different authentication types, refer to the following sections on prerequisites and JSON samples respectively:

Uso dell'autenticazione SQLUsing SQL authentication

Esempio di servizio collegato tramite l'autenticazione SQL:Linked service example using 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"
        }
    }
}

Uso dell'autenticazione basata sull'entità servizioUsing service principal authentication

Per usare l'autenticazione token dell'applicazione di AAD basata sull'entità servizio, seguire questa procedura:To use service principal based AAD application token authentication, follow these steps:

  1. Creare un'applicazione di Azure Active Directory nel portale di Azure.Create an Azure Active Directory application from Azure portal. Prendere nota del nome dell'applicazione e dei valori seguenti da usare per definire il servizio collegato:Make note of the application name, and the following values which you use to define the linked service:

    • ID applicazioneApplication ID
    • Chiave applicazioneApplication key
    • ID tenantTenant ID
  2. Effettuare il provisioning di un amministratore di Azure Active Directory per il server SQL di Azure nel portale di Azure, se l'operazione non è già stata eseguita.Provision an Azure Active Directory administrator for your Azure SQL Server on Azure portal if you haven't done so. L'amministratore di AAD può essere un utente o un gruppo di AAD.The AAD administrator can be an AAD user or AAD group. Se si concede al gruppo con identità del servizio gestito un ruolo di amministratore, ignorare i passaggi 3 e 4 riportati di seguito, in quanto l'amministratore avrà l'accesso completo al database.If you grant the group with MSI an admin role, skip step 3 and 4 below as the administrator would have full access to the DB.

  3. Creare un utente di database indipendente per l'entità servizio tramite la connessione al data warehouse da/verso cui si vogliono copiare i dati usando strumenti come SQL Server Management Studio, con un'identità di AAD che abbia almeno l'autorizzazione ALTER ANY USER, e l'esecuzione del comando in T-SQL seguente.Create a contained database user for the service principal, by connecting to the data warehouse from/to which you want to copy data using tools like SSMS, with an AAD identity having at least ALTER ANY USER permission, and executing the following T-SQL. Per altre informazioni sull'utente di database indipendente, consultare questo articolo.Learn more on contained database user from here.

    CREATE USER [your application name] FROM EXTERNAL PROVIDER;
    
  4. Concedere all'entità servizio le autorizzazioni necessarie, come si fa di norma per gli utenti SQL, ad esempio tramite l'esecuzione del codice seguente:Grant the service principal needed permissions as you normally do for SQL users, e.g. by executing below:

    EXEC sp_addrolemember '[your application name]', 'readonlyuser';
    
  5. Nel file di definizione dell'applicazione (ADF) configurare un servizio collegato ad Azure SQL Data Warehouse.In ADF, configure an Azure SQL Data Warehouse linked service.

Esempio di servizio collegato tramite l'autenticazione basata su entità servizio:Linked service example using 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"
        }
    }
}

Uso dell'autenticazione basata sull'identità del servizio gestitoUsing managed service identity authentication

Una data factory può essere associata a un'identità del servizio gestito, che rappresenta la data factory specifica.A data factory can be associated with a managed service identity (MSI), which represents this specific data factory. È possibile usare questa identità del servizio per l'autenticazione di Azure SQL Data Warehouse, che consente a questa factory designata di accedere e copiare i dati dal o nel database.You can use this service identity for Azure SQL Data Warehouse authentication, which allows this designated factory to access and copy data from/to your data warehouse.

Per usare l'autenticazione token dell'applicazione di AAD basata sull'identità del servizio gestito, seguire questa procedura:To use MSI based AAD application token authentication, follow these steps:

  1. Creare un gruppo in Azure AD e aggiungere l'identità del servizio gestito della factory come membro del gruppo.Create a group in Azure AD and make the factory MSI a member of the group.

    a.a. Trovare l'identità del servizio della data factory nel portale di Azure.Find the data factory service identity from Azure portal. Passare alla data factory -> Proprietà -> copiare il valore di ID IDENTITÀ DEL SERVIZIO.Go to your data factory -> Properties -> copy the SERVICE IDENTITY ID.

    b.b. Installare il modulo Azure AD PowerShell, eseguire l'accesso usando il comando Connect-AzureAD ed eseguire i comandi seguenti per creare un gruppo e aggiungere l'identità del servizio gestito della data factory come membro.Install the Azure AD PowerShell module, sign in using Connect-AzureAD command, and run the following commands to create a group and add the data factory MSI as a member.

    $Group = New-AzureADGroup -DisplayName "<your group name>" -MailEnabled $false -SecurityEnabled $true -MailNickName "NotSet"
    Add-AzureAdGroupMember -ObjectId $Group.ObjectId -RefObjectId "<your data factory service identity ID>"
    
  2. Effettuare il provisioning di un amministratore di Azure Active Directory per il server SQL di Azure nel portale di Azure, se l'operazione non è già stata eseguita.Provision an Azure Active Directory administrator for your Azure SQL Server on Azure portal if you haven't done so.

  3. Creare un utente di database indipendente per il gruppo di AAD tramite la connessione al data warehouse da/verso cui si vogliono copiare i dati usando strumenti come SQL Server Management Studio, con un'identità di AAD che abbia almeno l'autorizzazione ALTER ANY USER, e l'esecuzione del comando in T-SQL seguente.Create a contained database user for the AAD group, by connecting to the data warehouse from/to which you want to copy data using tools like SSMS, with an AAD identity having at least ALTER ANY USER permission, and executing the following T-SQL. Per altre informazioni sull'utente di database indipendente, consultare questo articolo.Learn more on contained database user from here.

    CREATE USER [your AAD group name] FROM EXTERNAL PROVIDER;
    
  4. Concedere al gruppo di AAD le autorizzazioni necessarie, come si fa di norma per gli utenti SQL, ad esempio tramite l'esecuzione del codice seguente:Grant the AAD group needed permissions as you normally do for SQL users, e.g. by executing below:

    EXEC sp_addrolemember '[your AAD group name]', 'readonlyuser';
    
  5. Nel file di definizione dell'applicazione (ADF) configurare un servizio collegato ad Azure SQL Data Warehouse.In ADF, configure an Azure SQL Data Warehouse linked service.

Esempio di servizio collegato tramite l'autenticazione basata sull'identità del servizio gestito:Linked service example using MSI authentication:

{
    "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"
        }
    }
}

Proprietà dei set di datiDataset properties

Per un elenco completo delle sezioni e delle proprietà disponibili per la definizione di set di dati, vedere l'articolo sui set di dati.For a full list of sections and properties available for defining datasets, see the datasets article. Questa sezione presenta un elenco delle proprietà supportate dal set di dati Azure SQL Data Warehouse.This section provides a list of properties supported by Azure SQL Data Warehouse dataset.

Per copiare dati da/in Azure SQL Data Warehouse, impostare la proprietà type del set di dati su AzureSqlDWTable.To copy data from/to Azure SQL Data Warehouse, set the type property of the dataset to AzureSqlDWTable. Sono supportate le proprietà seguenti:The following properties are supported:

ProprietàProperty DESCRIZIONEDescription ObbligatoriaRequired
typetype La proprietà type del set di dati deve essere impostata su: AzureSqlDWTableThe type property of the dataset must be set to: AzureSqlDWTable Yes
tableNametableName Nome della tabella o vista nell'istanza di Azure SQL Data Warehouse a cui fa riferimento il servizio collegato.Name of the table or view in the Azure SQL Data Warehouse instance that linked service refers to. Yes

Esempio:Example:

{
    "name": "AzureSQLDWDataset",
    "properties":
    {
        "type": "AzureSqlDWTable",
        "linkedServiceName": {
            "referenceName": "<Azure SQL Data Warehouse linked service name>",
            "type": "LinkedServiceReference"
        },
        "typeProperties": {
            "tableName": "MyTable"
        }
    }
}

Proprietà dell'attività di copiaCopy activity properties

Per un elenco completo delle sezioni e delle proprietà disponibili per la definizione delle attività, vedere l'articolo sulle pipeline.For a full list of sections and properties available for defining activities, see the Pipelines article. Questa sezione presenta un elenco delle proprietà supportate dall'origine e dal sink Azure SQL Data Warehouse.This section provides a list of properties supported by Azure SQL Data Warehouse source and sink.

Azure SQL Data Warehouse come origineAzure SQL Data Warehouse as source

Per copiare dati da Azure SQL Data Warehouse, impostare il tipo di origine nell'attività di copia su SqlDWSource.To copy data from Azure SQL Data Warehouse, set the source type in the copy activity to SqlDWSource. Nella sezione origine dell'attività di copia sono supportate le proprietà seguenti:The following properties are supported in the copy activity source section:

ProprietàProperty DESCRIZIONEDescription ObbligatoriaRequired
typetype La proprietà type dell'origine dell'attività di copia deve essere impostata su: SqlDWSourceThe type property of the copy activity source must be set to: SqlDWSource Yes
SqlReaderQuerysqlReaderQuery Usare la query SQL personalizzata per leggere i dati.Use the custom SQL query to read data. Esempio: select * from MyTable.Example: select * from MyTable. No No
sqlReaderStoredProcedureNamesqlReaderStoredProcedureName Nome della stored procedure che legge i dati dalla tabella di origine.Name of the stored procedure that reads data from the source table. L'ultima istruzione SQL deve essere un'istruzione SELECT nella stored procedure.The last SQL statement must be a SELECT statement in the stored procedure. No No
storedProcedureParametersstoredProcedureParameters Parametri per la stored procedure.Parameters for the stored procedure.
I valori consentiti sono: coppie nome/valore.Allowed values are: name/value pairs. I nomi e le maiuscole e minuscole dei parametri devono corrispondere ai nomi e alle maiuscole e minuscole dei parametri della stored procedure.Names and casing of parameters must match the names and casing of the stored procedure parameters.
No No

Punti da notare:Points to note:

  • Se per SqlSource è specificata la proprietà sqlReaderQuery, l'attività di copia esegue questa query nell'origine Azure SQL Data Warehouse per ottenere i dati.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. In alternativa, è possibile specificare una stored procedure indicando i parametri sqlReaderStoredProcedureName e storedProcedureParameters (se la stored procedure accetta parametri).Alternatively, you can specify a stored procedure by specifying the sqlReaderStoredProcedureName and storedProcedureParameters (if the stored procedure takes parameters).
  • Se non si specifica né "sqlReaderQuery" né "sqlReaderStoredProcedureName", le colonne definite nella sezione "struttura" del set di dati JSON vengono usate per creare una query, select column1, column2 from mytable, da eseguire in Azure SQL Data Warehouse.If you do not 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) to run against the Azure SQL Data Warehouse. Se nella definizione del set di dati non è inclusa la "struttura", vengono selezionate tutte le colonne della tabella.If the dataset definition does not have the "structure", all columns are selected from the table.
  • Quando si usa sqlReaderStoredProcedureName è necessario specificare un valore fittizio per la proprietà tableName nel set di dati JSON.When you use sqlReaderStoredProcedureName, you still need to specify a dummy tableName property in the dataset JSON.

Esempio: uso della query SQLExample: using SQL query

"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>"
            }
        }
    }
]

Esempio: uso della stored procedureExample: using stored procedure

"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>"
            }
        }
    }
]

Definizione della stored procedure:The 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 Warehouse come sinkAzure SQL Data Warehouse as sink

Per copiare dati in Azure SQL Data Warehouse, impostare il tipo di sink nell'attività di copia su SqlDWSink.To copy data to Azure SQL Data Warehouse, set the sink type in the copy activity to SqlDWSink. Nella sezione sink dell'attività di copia sono supportate le proprietà seguenti:The following properties are supported in the copy activity sink section:

ProprietàProperty DESCRIZIONEDescription ObbligatoriaRequired
typetype La proprietà type del sink dell'attività di copia deve essere impostata su: SqlDWSinkThe type property of the copy activity sink must be set to: SqlDWSink Yes
allowPolyBaseallowPolyBase Indica se usare PolyBase, quando applicabile, invece del meccanismo BULKINSERT.Indicates whether to use PolyBase (when applicable) instead of BULKINSERT mechanism.

L'uso di PolyBase è il modo consigliato per caricare dati in SQL Data Warehouse.Using PolyBase is the recommended way to load data into SQL Data Warehouse. Per informazioni su vincoli e dettagli, vedere la sezione Usare PolyBase per caricare dati in Azure SQL Data Warehouse .See Use PolyBase to load data into Azure SQL Data Warehouse section for constraints and details.

I valori consentiti sono: True (predefinito), False.Allowed values are: True (default), and False.
No No
polyBaseSettingspolyBaseSettings Gruppo di proprietà che è possibile specificare quando la proprietà allowPolybase è impostata su true.A group of properties that can be specified when the allowPolybase property is set to true. No No
rejectValuerejectValue Specifica il numero o la percentuale di righe che è possibile rifiutare prima che la query abbia esito negativo.Specifies the number or percentage of rows that can be rejected before the query fails.

Per altre informazioni sulle opzioni di rifiuto di PolyBase, vedere la sezione Arguments (Argomenti) in CREATE EXTERNAL TABLE (Transact-SQL) .Learn more about the PolyBase’s reject options in the Arguments section of CREATE EXTERNAL TABLE (Transact-SQL) topic.

I valori consentiti sono: 0 (predefinito), 1, 2, ...Allowed values are: 0 (default), 1, 2, …
No No
rejectTyperejectType Indica se l'opzione rejectValue viene specificata come valore letterale o come percentuale.Specifies whether the rejectValue option is specified as a literal value or a percentage.

I valori consentiti sono: Valore (predefinito), Percentuale.Allowed values are: Value (default), and Percentage.
No No
rejectSampleValuerejectSampleValue Determina il numero di righe da recuperare prima che PolyBase ricalcoli la percentuale di righe rifiutate.Determines the number of rows to retrieve before the PolyBase recalculates the percentage of rejected rows.

I valori consentiti sono: 1, 2, …Allowed values are: 1, 2, …
Sì se rejectType è percentageYes, if rejectType is percentage
useTypeDefaultuseTypeDefault Specifica come gestire i valori mancanti nei file con testo delimitato quando PolyBase recupera dati dal file di testo.Specifies how to handle missing values in delimited text files when PolyBase retrieves data from the text file.

Per altre informazioni su questa proprietà, vedere la sezione Arguments (Argomenti) in CREATE EXTERNAL FILE FORMAT (Transact-SQL).Learn more about this property from the Arguments section in CREATE EXTERNAL FILE FORMAT (Transact-SQL).

I valori consentiti sono: True, False (predefinito).Allowed values are: True, False (default).
No No
writeBatchSizewriteBatchSize Inserisce dati nella tabella SQL quando la dimensione del buffer raggiunge writeBatchSize.Inserts data into the SQL table when the buffer size reaches writeBatchSize. Si applica solo se non viene usato PolyBase.Applies only when PolyBase is not used.

I valori consentiti sono: integer (numero di righe).Allowed values are: integer (number of rows).
No (il valore predefinito è 10.000)No (default is 10000)
writeBatchTimeoutwriteBatchTimeout Tempo di attesa per l'operazione di inserimento batch da completare prima del timeout. Si applica solo se non viene usato PolyBase.Wait time for the batch insert operation to complete before it times out. Applies only when PolyBase is not used.

I valori consentiti sono: intervallo di tempo.Allowed values are: timespan. Ad esempio: "00:30:00" (30 minuti).Example: “00:30:00” (30 minutes).
No No
preCopyScriptpreCopyScript Specificare una query SQL per l'attività di copia da eseguire prima di scrivere i dati in Azure SQL Data Warehouse ad ogni esecuzione.Specify a SQL query for Copy Activity to execute before writing data into Azure SQL Data Warehouse in each run. È possibile usare questa proprietà per pulire i dati precaricati.You can use this property to clean up the pre-loaded data. No No

Esempio:Example:

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

Per altre informazioni su come usare PolyBase per caricare in modo efficiente in SQL Data Warehouse, vedere la sezione successiva.Learn more on how to use PolyBase to load into SQL Data Warehouse efficiently from next section.

Usare PolyBase per caricare dati in Azure SQL Data WarehouseUse PolyBase to load data into Azure SQL Data Warehouse

PolyBase consente di caricare con efficacia grandi quantità di dati in Azure SQL Data Warehouse con una velocità effettiva elevata.Using PolyBase is an efficient way of loading large amount of data into Azure SQL Data Warehouse with high throughput. L'uso di PolyBase consente un miglioramento significativo della velocità effettiva rispetto al meccanismo BULKINSERT predefinito.You can see a large gain in the throughput by using PolyBase instead of the default BULKINSERT mechanism. Vedere Copiare il numero di riferimento prestazioni con il confronto dettagliato.See copy performance reference number with detailed comparison. Per la procedura dettagliata con un caso d'uso, vedere Caricare 1 TB di dati in Azure SQL Data Warehouse in meno di 15 minuti con Azure Data Factory.For a walkthrough with a use case, see Load 1 TB into Azure SQL Data Warehouse under 15 minutes with Azure Data Factory.

  • Se il formato dei dati di origine è BLOB di Azure o Azure Data Lake Store e compatibile con PolyBase, è possibile eseguire la copia direttamente in Azure SQL Data Warehouse usando PolyBase.If your source data is in Azure Blob or Azure Data Lake Store, and the format is compatible with PolyBase, you can directly copy to Azure SQL Data Warehouse using PolyBase. Vedere Copia diretta tramite PolyBase con i relativi dettagli.See Direct copy using PolyBase with details.
  • Se l'archivio e il formato dei dati di origine non sono supportati in origine da PolyBase, è possibile usare la funzione copia di staging tramite PolyBase.If your source data store and format is not originally supported by PolyBase, you can use the Staged Copy using PolyBase feature instead. Viene inoltre generata una migliore velocità effettiva tramite la conversione automatica dei dati nel formato compatibile con PolyBase e l'archiviazione dei dati in Archiviazione BLOB di Azure.It also provides you better throughput by automatically converting the data into PolyBase-compatible format and storing the data in Azure Blob storage. Vengono quindi caricati i dati in SQL Data Warehouse.It then loads data into SQL Data Warehouse.

Importante

Si noti che PolyBase supporta solo l'autenticazione SQL di Azure SQL Data Warehouse, non l'autenticazione Azure Active Directory.

Copia diretta tramite PolyBaseDirect copy using PolyBase

PolyBase di SQL Data Warehouse supporta direttamente Archiviazione BLOB di Azure e Azure Data Lake Store (mediante l'entità servizio) come origine e con requisiti di formato di file specifico.SQL Data Warehouse PolyBase directly support Azure Blob and Azure Data Lake Store (using service principal) as source and with specific file format requirements. Se i dati di origine soddisfano i criteri descritti in questa sezione, è possibile eseguire la copia direttamente dall'archivio dati di origine ad Azure SQL Data Warehouse con PolyBase.If your source data meets the criteria described in this section, you can directly copy from source data store to Azure SQL Data Warehouse using PolyBase. In caso contrario è possibile usare la copia di staging tramite PolyBase.Otherwise, you can use Staged Copy using PolyBase.

Suggerimento

Nell'articolo Azure Data Factory makes it even easier and convenient to uncover insights from data when using Data Lake Store with SQL Data Warehouse (Con Azure Data Factory è ancora più semplice e pratico individuare informazioni utili sui dati quando si usa Data Lake Store con SQL Data Warehouse) sono indicate altre informazioni utili per copiare efficacemente i dati da Data Lake Store a SQL Data Warehouse.

Se i requisiti non vengono soddisfatti, Azure Data Factory controlla le impostazioni e usa automaticamente il meccanismo BULKINSERT per lo spostamento dei dati.If the requirements are not met, Azure Data Factory checks the settings and automatically falls back to the BULKINSERT mechanism for the data movement.

  1. Il servizio collegato all'origine è di tipo: AzureStorage o AzureDataLakeStore con autenticazione entità servizio.Source linked service is of type: AzureStorage or AzureDataLakeStore with service principal authentication.
  2. Il set di dati di input è di tipo AzureBlob o AzureDataLakeStoreFile e il tipo di formato nelle proprietà type è OrcFormat ParquetFormat o TextFormat, con le configurazioni seguenti:The input dataset is of type: AzureBlob or AzureDataLakeStoreFile, and the format type under type properties is OrcFormat, ParquetFormat, or TextFormat with the following configurations:

    1. rowDelimiter deve essere \n.rowDelimiter must be \n.
    2. nullValue è impostato su stringa vuota ("") o treatEmptyAsNull è impostato su true.nullValue is set to empty string (""), or treatEmptyAsNull is set to true.
    3. encodingName è impostato su utf-8, ovvero il valore predefinito.encodingName is set to utf-8, which is default value.
    4. escapeChar, quoteChar, firstRowAsHeader e skipLineCount non sono specificati.escapeChar, quoteChar, firstRowAsHeader, and skipLineCount are not specified.
    5. compression può essere no compression, GZip o Deflate.compression can be no compression, GZip, or Deflate.

      "typeProperties": {
       "folderPath": "<blobpath>",
       "format": {
           "type": "TextFormat",
           "columnDelimiter": "<any delimiter>",
           "rowDelimiter": "\n",
           "nullValue": "",
           "encodingName": "utf-8"
       },
       "compression": {
           "type": "GZip",
           "level": "Optimal"
       }
      },
      
  3. Non è disponibile alcuna impostazione skipHeaderLineCount in BlobSource o AzureDataLakeStore per l'attività di copia nella pipeline.There is no skipHeaderLineCount setting under BlobSource or AzureDataLakeStore for the Copy activity in the pipeline.

  4. Non è disponibile alcuna impostazione sliceIdentifierColumnName in SqlDWSink per l'attività di copia nella pipeline.There is no sliceIdentifierColumnName setting under SqlDWSink for the Copy activity in the pipeline. PolyBase garantisce che tutti i dati verranno aggiornati o che nessun dato verrà aggiornato in una singola esecuzione.(PolyBase guarantees that all data is updated or nothing is updated in a single run. Per ottenere la ripetibilità, è possibile usare sqlWriterCleanupScript.To achieve repeatability, you could use sqlWriterCleanupScript).
"activities":[
    {
        "name": "CopyFromAzureBlobToSQLDataWarehouseViaPolyBase",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "BlobDataset",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "AzureSQLDWDataset",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "BlobSource",
            },
            "sink": {
                "type": "SqlDWSink",
                "allowPolyBase": true
            }
        }
    }
]

copia di staging tramite PolyBaseStaged Copy using PolyBase

Quando i dati di origine non soddisfano i criteri presentati nella sezione precedente, è possibile abilitare la copia dei dati tramite un'istanza di Archiviazione BLOB di Azure di gestione temporanea provvisoria (non può essere Archiviazione Premium).When your source data doesn’t meet the criteria introduced in the previous section, you can enable copying data via an interim staging Azure Blob Storage (cannot be Premium Storage). In questo caso, Azure Data Factory esegue automaticamente trasformazioni sui dati in modo che soddisfino i requisiti di formato dei dati di PolyBase e quindi usa PolyBase per caricare dati in SQL Data Warehouse e infine pulisce i dati temporanei dall'archiviazione BLOB.In this case, Azure Data Factory automatically performs transformations on the data to meet data format requirements of PolyBase, then use PolyBase to load data into SQL Data Warehouse, and then clean-up your temp data from the Blob storage. Per informazioni dettagliate sul funzionamento generale della copia dei dati tramite un BLOB di Azure di staging, vedere la sezione Copia di staging .See Staged Copy for details on how copying data via a staging Azure Blob works in general.

Per usare questa funzionalità, creare un servizio collegato Archiviazione di Azure che faccia riferimento all'account di archiviazione di Azure contenente l'archivio BLOB provvisorio e quindi specificare le proprietà enableStaging e stagingSettings per l'attività di copia come illustrato nel codice seguente:To use this feature, create an Azure Storage linked service that refers to the Azure Storage Account that has the interim blob storage, then specify the enableStaging and stagingSettings properties for the Copy Activity as shown in the following code:

"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"
                }
            }
        }
    }
]

Procedure consigliate per l'uso di PolyBaseBest practices when using PolyBase

Le sezioni seguenti forniscono procedure consigliate aggiuntive a quelle descritte in Procedure consigliate per Azure SQL Data Warehouse.The following sections provide additional best practices to the ones that are mentioned in Best practices for Azure SQL Data Warehouse.

Autorizzazione database obbligatoriaRequired database permission

Per usare PolyBase, è necessario che l'utente che è solito caricare i dati in SQL Data Warehouse disponga dell'autorizzazione "CONTROL" nel database di destinazione.To use PolyBase, it requires the user being used to load data into SQL Data Warehouse has the "CONTROL" permission on the target database. Un modo per ottenere questo risultato consiste nell'aggiungere tale utente come membro del ruolo "db_owner".One way to achieve that is to add that user as a member of "db_owner" role. Informazioni su come eseguire questa operazione sono disponibili nella sezione seguente.Learn how to do that by following this section.

Limitazione alle dimensioni di righe e al tipo di datiRow size and data type limitation

Le operazioni di caricamento di PolyBase sono limitate al caricamento di righe inferiori a 1 MB che non possono essere caricate in VARCHR(MAX), NVARCHAR(MAX) o VARBINARY(MAX).Polybase loads are limited to loading rows both smaller than 1 MB and cannot load to VARCHR(MAX), NVARCHAR(MAX) or VARBINARY(MAX). Vedere qui.Refer to here.

Se sono presenti dati di origine con righe di dimensioni superiori a 1 MB, è consigliabile suddividere verticalmente le tabelle di origine in tabelle più piccole, in cui le dimensioni massime delle righe di ogni tabella non superano il limite previsto.If you have source data with rows of size greater than 1 MB, you may want to split the source tables vertically into several small ones where the largest row size of each of them does not exceed the limit. Le tabelle più piccole possono essere quindi caricate usando PolyBase e unite in Azure SQL Data Warehouse.The smaller tables can then be loaded using PolyBase and merged together in Azure SQL Data Warehouse.

Classe di risorse di SQL Data WarehouseSQL Data Warehouse resource class

Per ottenere le migliori prestazioni possibili, considerare l'assegnazione di una classe di risorse più ampia all'utente che carica i dati in SQL Data Warehouse tramite PolyBase.To achieve best possible throughput, consider assigning a larger resource class to the user being used to load data into SQL Data Warehouse via PolyBase.

tableName in Azure SQL Data WarehousetableName in Azure SQL Data Warehouse

La tabella seguente fornisce esempi relativi a come specificare la proprietà tableName nel set di dati JSON per diverse combinazioni di nomi di schema e di tabella.The following table provides examples on how to specify the tableName property in dataset JSON for various combinations of schema and table name.

Schema di databaseDB Schema Nome tabellaTable name Proprietà JSON tableNametableName JSON property
dbodbo MyTableMyTable MyTable o dbo.MyTable o [dbo].[MyTable]MyTable or dbo.MyTable or [dbo].[MyTable]
dbo1dbo1 MyTableMyTable dbo1.MyTable o [dbo1].[MyTable]dbo1.MyTable or [dbo1].[MyTable]
dbodbo My.TableMy.Table [My.Table] o [dbo].[My.Table][My.Table] or [dbo].[My.Table]
dbo1dbo1 My.TableMy.Table [dbo1].[My.Table][dbo1].[My.Table]

Se viene visualizzato l'errore seguente, potrebbe essersi verificato un problema con il valore specificato per la proprietà tableName.If you see the following error, it could be an issue with the value you specified for the tableName property. Per informazioni sul modo corretto di specificare i valori per la proprietà JSON tableName, vedere la relativa tabella.See the 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

Colonne con valori predefinitiColumns with default values

La funzionalità PolyBase in Data Factory accetta attualmente lo stesso numero di colonne disponibili nella tabella di destinazione.Currently, PolyBase feature in Data Factory only accepts the same number of columns as in the target table. Se si ha una tabella con quattro colonne di cui una definita con un valore predefinito, ad esempio,Say, you have a table with four columns and one of them is defined with a default value. i dati di input dovranno comunque contenere quattro colonne.The input data should still contain four columns. Se si specifica un set di dati di input con 3 colonne, si verificherà un errore simile al messaggio seguente:Providing a 3-column input dataset would yield an error similar to the following message:

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

Il valore NULL è una forma speciale di valore predefinito.NULL value is a special form of default value. Se la colonna ammette valori Null, i dati di input (nel BLOB) per tale colonna possono essere vuoti, ma non possono essere mancanti dal set di dati di input.If the column is nullable, the input data (in blob) for that column could be empty (cannot be missing from the input dataset). PolyBase inserisce NULL per tali valori in Azure SQL Data Warehouse.PolyBase inserts NULL for them in the Azure SQL Data Warehouse.

Mapping dei tipi di dati per Azure SQL Data WarehouseData type mapping for Azure SQL Data Warehouse

Quando si copiano i dati/in Azure SQL Data Warehouse, vengono usati i mapping seguenti tra i tipi di dati di Azure SQL Data Warehouse e i tipi di dati provvisori di Azure Data Factory.When copying data from/to Azure SQL Data Warehouse, the following mappings are used from Azure SQL Data Warehouse data types to Azure Data Factory interim data types. Vedere Mapping dello schema e del tipo di dati per informazioni su come l'attività di copia esegue il mapping dello schema di origine e del tipo di dati al sink.See Schema and data type mappings to learn about how copy activity maps the source schema and data type to the sink.

Tipo di dati di Azure SQL Data WarehouseAzure SQL Data Warehouse data type Tipo di dati provvisori di Data FactoryData 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
immagineimage Byte[]Byte[]
intint Int32Int32
moneymoney DecimalDecimal
ncharnchar String, Char[]String, Char[]
ntextntext String, Char[]String, Char[]
numericnumeric DecimalDecimal
nvarcharnvarchar String, Char[]String, Char[]
realreal SingleSingle
rowversionrowversion Byte[]Byte[]
smalldatetimesmalldatetime DatetimeDateTime
smallintsmallint Int16Int16
smallmoneysmallmoney DecimalDecimal
sql_variantsql_variant Object *Object *
texttext String, Char[]String, Char[]
timetime Intervallo di tempoTimeSpan
timestamptimestamp Byte[]Byte[]
tinyinttinyint ByteByte
uniqueidentifieruniqueidentifier GuidGuid
varbinaryvarbinary Byte[]Byte[]
varcharvarchar String, Char[]String, Char[]
xmlxml xmlXml

Passaggi successiviNext steps

Per un elenco degli archivi dati supportati come origini o sink dall'attività di copia in Azure Data Factory, vedere gli archivi dati supportati.For a list of data stores supported as sources and sinks by the copy activity in Azure Data Factory, see supported data stores.