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 in o da Azure SQL Data Warehouse.This article explains how to use Copy Activity in Azure Data Factory to copy data to or from Azure SQL Data Warehouse. Si basa sull'articolo di panoramica dell'attività di copia che presenta informazioni generali sull'attività di copia.It builds on the Copy Activity overview article that presents a general overview of Copy Activity.

Funzionalità supportateSupported capabilities

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

In particolare, il connettore Azure SQL Data Warehouse supporta queste funzioni:Specifically, this Azure SQL Data Warehouse connector supports these functions:

  • La copia di dati tramite l'autenticazione SQL e l'autenticazione token dell'applicazione Azure Active Directory (Azure AD) con entità servizio o identità del servizio gestita.Copy data by using SQL authentication and Azure Active Directory (Azure AD) Application token authentication with a service principal or Managed Service Identity (MSI).
  • Come origine, il recupero di dati tramite query SQL o stored procedure.As a source, retrieve data by using a SQL query or stored procedure.
  • Come sink, il caricamento di dati tramite PolyBase o un inserimento bulk.As a sink, load data by using PolyBase or a bulk insert. Per ottimizzare le prestazioni di copia, è consigliabile usare PolyBase.We recommend PolyBase for better copy performance.

Importante

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

Importante

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

Attività inizialiGet started

Suggerimento

Per ottenere prestazioni ottimali, usare PolyBase per caricare i dati in Azure SQL Data Warehouse. Vedere la sezione Usare PolyBase per caricare dati in Azure SQL Data Warehouse per i dettagli. 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.

È 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 informazioni dettagliate sulle proprietà che definiscono entità di Data Factory specifiche per il connettore Azure SQL Data Warehouse.The following sections provide details about properties that define Data Factory entities specific to an 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 an Azure SQL Data Warehouse linked service:

ProprietàProperty DESCRIZIONEDescription ObbligatoriaRequired
typetype La proprietà type deve essere impostata su AzureSqlDW.The 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 the 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 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 Azure AD con un'entità servizio.Yes, when you use Azure AD authentication with a 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 Azure AD con un'entità servizio.Yes, when you use Azure AD authentication with a 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 top-right corner of the Azure portal. Sì, quando si usa l'autenticazione Azure AD con un'entità servizio.Yes, when you use Azure AD authentication with a service principal.
connectViaconnectVia 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 un runtime di integrazione self-hosted (se l'archivio dati si trova in una rete privata).You can use Azure Integration Runtime or a self-hosted integration runtime (if your data store is located in a 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:

Autenticazione in SQLSQL authentication

Esempio di servizio collegato tramite l'autenticazione SQLLinked 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"
        }
    }
}

Autenticazione di un'entità servizioService principal authentication

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

  1. Creare un'applicazione Azure Active Directory nel portale di Azure.Create an Azure Active Directory application from the Azure portal. Prendere nota del nome dell'applicazione e dei valori seguenti che definiscono il servizio collegato:Make note of the application name and the following values that 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 the Azure portal if you haven't already done so. L'amministratore di Azure AD può essere un utente o un gruppo di Azure AD.The Azure AD administrator can be an Azure AD user or Azure AD group. Se si concede il ruolo di amministratore al gruppo con l'identità del servizio gestita, ignorare i passaggi 3 e 4.If you grant the group with MSI an admin role, skip steps 3 and 4. L'amministratore avrà accesso completo al database.The administrator will have full access to the database.

  3. Creare utenti del database indipendente per l'entità servizio.Create contained database users for the service principal. Connettersi al data warehouse da o in cui si vogliono copiare i dati usando strumenti come SSMS, con un'identità di Azure AD che abbia almeno l'autorizzazione ALTER ANY USER.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. Eseguire il comando in T-SQL seguente:Run the following T-SQL:

    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 o altri utenti.Grant the service principal needed permissions as you normally do for SQL users or others. Eseguire il codice seguente:Run the following code:

    EXEC sp_addrolemember [role name], [your application name];
    
  5. Configurare un servizio collegato ad Azure SQL Data Warehouse in Azure Data Factory.Configure an Azure SQL Data Warehouse linked service in Azure Data Factory.

Esempio di servizio collegato tramite l'autenticazione basata su entità servizioLinked 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"
        }
    }
}

Autenticazione basata su identità del servizio gestitaManaged Service Identity authentication

Una data factory può essere associata a un'identità del servizio gestita, che rappresenta la factory specifica.A data factory can be associated with a Managed Service Identity that represents the specific factory. È possibile usare questa identità del servizio per l'autenticazione di Azure SQL Data Warehouse.You can use this service identity for Azure SQL Data Warehouse authentication. La factory designata può accedere ai dati e copiarli da o nel data warehouse tramite questa identità.The designated factory can access and copy data from or to your data warehouse by using this identity.

Importante

Si noti che PolyBase non è attualmente supportato per l'autenticazione tramite l'identità del servizio gestita.

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

  1. Creare un gruppo in Azure AD.Create a group in Azure AD. Aggiungere l'identità del servizio gestita della factory come membro del gruppo.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 the Azure portal. Accedere alle proprietà della data factory.Go to your data factory's Properties. Copiare l'ID IDENTITÀ DEL SERVIZIO.Copy the SERVICE IDENTITY ID.

    b.b. Installare il modulo Azure AD PowerShell.Install the Azure AD PowerShell module. Accedere usando il comando Connect-AzureAD.Sign in by using the Connect-AzureAD command. Eseguire i comandi seguenti per creare un gruppo e aggiungere come membro l'identità del servizio gestita della data factory.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 the Azure portal if you haven't already done so.

  3. Creare utenti del database indipendente per il gruppo di Azure AD.Create contained database users for the Azure AD group. Connettersi al data warehouse da o in cui si vogliono copiare i dati usando strumenti come SSMS, con un'identità di Azure AD che abbia almeno l'autorizzazione ALTER ANY USER.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. Eseguire il comando in T-SQL seguente.Run the following T-SQL.

    CREATE USER [your Azure AD group name] FROM EXTERNAL PROVIDER;
    
  4. Concedere al gruppo di Azure AD le autorizzazioni necessarie, come si fa di norma per gli utenti SQL e altri utenti.Grant the Azure AD group needed permissions as you normally do for SQL users and others. Ad esempio, eseguire il codice seguente.For example, run the following code.

    EXEC sp_addrolemember [role name], [your Azure AD group name];
    
  5. Configurare un servizio collegato ad Azure SQL Data Warehouse in Azure Data Factory.Configure an Azure SQL Data Warehouse linked service in Azure Data Factory.

Esempio di servizio collegato tramite l'autenticazione dell'identità del servizio gestitaLinked service example that uses 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 dei set di dati, vedere l'articolo 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 the Azure SQL Data Warehouse dataset.

Per copiare dati da o in Azure SQL Data Warehouse, impostare la proprietà type del set di dati su AzureSqlDWTable.To copy data from or 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 AzureSqlDWTable.The 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.The name of the table or view in the Azure SQL Data Warehouse instance that the linked service refers to. Yes

Esempio di proprietà dei set di datiDataset properties 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 the Azure SQL Data Warehouse source and sink.

Azure SQL Data Warehouse come origineAzure SQL Data Warehouse as the source

Per copiare dati da Azure SQL Data Warehouse, impostare la proprietà type nell'origine dell'attività di copia su SqlDWSource.To copy data from Azure SQL Data Warehouse, set the type property in the Copy Activity source to SqlDWSource. Nella sezione source 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 SqlDWSource.The 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.The 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 or 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 notarePoints 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.Or you can specify a stored procedure. Indicare i parametri sqlReaderStoredProcedureName e storedProcedureParameters (se accettati dalla stored procedure).Specify the sqlReaderStoredProcedureName and storedProcedureParameters if the stored procedure takes parameters.
  • Se non si specifica né sqlReaderQuerysqlReaderStoredProcedureName, le colonne definite nella sezione della struttura del set di dati JSON vengono usate per creare una query.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 viene eseguito in Azure SQL Data Warehouse.select column1, column2 from mytable runs against Azure SQL Data Warehouse. Se la definizione del set di dati non include la struttura, vengono selezionate tutte le colonne della tabella.If the dataset definition doesn't 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 di query SQLSQL 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>"
            }
        }
    }
]

Esempio di stored procedureStored 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>"
            }
        }
    }
]

Definizione della stored procedureStored 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 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 SqlDWSink.The 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 the BULKINSERT mechanism.

È consigliabile caricare dati in SQL Data Warehouse tramite PolyBase.We recommend that you load data into SQL Data Warehouse by using PolyBase. Per informazioni su vincoli e dettagli, vedere la sezione Usare PolyBase per caricare dati in Azure SQL Data Warehouse.See the Use PolyBase to load data into Azure SQL Data Warehouse section for constraints and details.

I valori consentiti sono True e False (predefinito).Allowed values are True and False (default).
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 Argomenti in CREATE EXTERNAL TABLE (Transact-SQL).Learn more about PolyBase’s reject options in the Arguments section of CREATE EXTERNAL TABLE (Transact-SQL).

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

I valori consentiti sono Value (predefinito) e Percentage.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 PolyBase recalculates the percentage of rejected rows.

I valori consentiti sono 1, 2 e così via.Allowed values are 1, 2, etc.
Sì se rejectType è percentage.Yes, if the 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 e False (predefinito).Allowed values are True and 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 isn't used.

Il valore consentito è integer (numero di righe).The allowed value is integer (number of rows).
No.No. Il valore predefinito è 10000.The default is 10000.
writeBatchTimeoutwriteBatchTimeout Tempo di attesa per il completamento dell'operazione di inserimento batch prima del timeout. Si applica solo se non viene usato PolyBase.Wait time for the batch insert operation to finish before it times out. Applies only when PolyBase isn't used.

Il valore consentito è timespan.The allowed value is 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 run before writing data into Azure SQL Data Warehouse in each run. Usare questa proprietà per pulire i dati precaricati.Use this property to clean up the preloaded data. No No

Esempio di sink di SQL Data WarehouseSQL Data Warehouse sink 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 about how to use PolyBase to efficiently load SQL Data Warehouse in the 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 in modo efficiente grandi quantità di dati in Azure SQL Data Warehouse con una velocità effettiva elevata.Using PolyBase is an efficient way to load a 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'll see a large gain in the throughput by using PolyBase instead of the default BULKINSERT mechanism. Vedere Informazioni di riferimento sulle prestazioni per un confronto dettagliato.See Performance reference for a detailed comparison. Per la procedura dettagliata con un caso d'uso, vedere Caricare 1 TB di dati in Azure SQL Data Warehouse.For a walkthrough with a use case, see Load 1 TB into Azure SQL Data Warehouse.

  • Se il formato dei dati di origine è Archiviazione BLOB di Azure o Azure Data Lake Store ed è compatibile con PolyBase, copiare direttamente in Azure SQL Data Warehouse usando PolyBase.If your source data is in Azure Blob storage or Azure Data Lake Store, and the format is compatible with PolyBase, copy direct to Azure SQL Data Warehouse by using PolyBase. Per maggiori dettagli, vedere Copia diretta tramite PolyBase.For details, see Direct copy by using PolyBase.
  • Se l'archivio e il formato dei dati di origine non sono supportati in origine da PolyBase, usare la funzionalità copia di staging tramite PolyBase.If your source data store and format isn't originally supported by PolyBase, use the Staged copy by using PolyBase feature instead. La funzionalità copia di staging assicura inoltre una migliore velocità effettiva,The staged copy feature also provides you better throughput. converte automaticamente i dati nel formato compatibile con PolyBaseIt automatically converts the data into PolyBase-compatible format. e li archivia in Archiviazione BLOB di Azure.And it stores the data in Azure Blob storage. Vengono quindi caricati i dati in SQL Data Warehouse.It then loads the data into SQL Data Warehouse.

Importante

Si noti che PolyBase non è attualmente supportato per l'autenticazione token dell'applicazione Azure AD basata sull'identità del servizio gestita.

Copia diretta tramite PolyBaseDirect copy by using PolyBase

PolyBase di SQL Data Warehouse supporta direttamente Archiviazione BLOB di Azure e Azure Data Lake Store.SQL Data Warehouse PolyBase directly supports Azure Blob and Azure Data Lake Store. Usa un'entità servizio come origine e ha requisiti di formato di file specifici.It uses service principal as a source and has specific file format requirements. Se i dati di origine soddisfano i criteri descritti in questa sezione, usare PolyBase per copiare direttamente dall'archivio dati di origine ad Azure SQL Data Warehouse.If your source data meets the criteria described in this section, use PolyBase to copy direct from the source data store to Azure SQL Data Warehouse. In caso contrario, usare la copia di staging tramite PolyBase.Otherwise, use Staged copy by 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 i dati in modo efficace 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 aren't met, Azure Data Factory checks the settings and automatically falls back to the BULKINSERT mechanism for the data movement.

  1. Il tipo di servizio collegato all'origine è AzureStorage o AzureDataLakeStore con autenticazione entità servizio.The Source linked service type is AzureStorage or AzureDataLakeStore with service principal authentication.
  2. Il tipo di set di dati di input è AzureBlob o AzureDataLakeStoreFile.The input dataset type is AzureBlob or AzureDataLakeStoreFile. Il tipo di formato nelle proprietà type è OrcFormat, ParquetFormat o TextFormat, con le configurazioni seguenti: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 the default value.
    4. escapeChar, quoteChar, firstRowAsHeader e skipLineCount non sono specificati.escapeChar, quoteChar, firstRowAsHeader, and skipLineCount aren't 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's no skipHeaderLineCount setting under BlobSource or AzureDataLakeStore for Copy Activity in the pipeline.

  4. Non è disponibile alcuna impostazione sliceIdentifierColumnName in SqlDWSink per l'attività di copia nella pipeline.There's no sliceIdentifierColumnName setting under SqlDWSink for 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à, usare sqlWriterCleanupScript.To achieve repeatability, 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 by using PolyBase

Quando i dati di origine non soddisfano i criteri della sezione precedente, abilitare la copia dei dati tramite un'istanza di Archiviazione BLOB di Azure di staging provvisoria.When your source data doesn’t meet the criteria in the previous section, enable data copying via an interim staging Azure Blob storage instance. Non può essere Archiviazione Premium di Azure.It can't be Azure 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.In this case, Azure Data Factory automatically runs transformations on the data to meet the data format requirements of PolyBase. Quindi usa PolyBase per caricare i dati in SQL Data Warehouse.Then it uses PolyBase to load data into SQL Data Warehouse. Infine, pulisce i dati temporanei dall'archiviazione BLOB.Finally, it cleans up your temporary data from the blob storage. Per informazioni dettagliate sulla copia dei dati tramite un'istanza di Archiviazione BLOB di Azure di staging, vedere Copia di staging.See Staged copy for details about copying data via a staging Azure Blob storage instance.

Per usare questa funzionalità, creare un servizio collegato Archiviazione di Azure che faccia riferimento all'account di archiviazione di Azure con l'archivio BLOB provvisorio.To use this feature, create an Azure Storage linked service that refers to the Azure storage account with the interim blob storage. Quindi specificare le proprietà enableStaging e stagingSettings per l'attività di copia come illustrato nel codice seguente: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 for using PolyBase

Le sezioni seguenti forniscono procedure consigliate in aggiunta a quelle descritte in Procedure consigliate per Azure SQL Data Warehouse.The following sections provide best practices in addition to those mentioned in Best practices for Azure SQL Data Warehouse.

Autorizzazione database obbligatoriaRequired database permission

Per usare PolyBase, l'utente che carica i dati in SQL Data Warehouse deve disporre dell'autorizzazione "CONTROL" nel database di destinazione.To use PolyBase, the user that loads data into SQL Data Warehouse must have "CONTROL" permission on the target database. Un modo per ottenere questo risultato consiste nell'aggiungere l'utente come membro del ruolo db_owner.One way to achieve that is to add the user as a member of the db_owner role. Informazioni su come eseguire questa operazione sono disponibili in Panoramica di SQL Data Warehouse.Learn how to do that in the SQL Data Warehouse overview.

Limitazioni alle dimensioni delle righe e al tipo di datiRow size and data type limits

Le operazioni di caricamento di PolyBase sono limitate alle righe inferiori a 1 MB,PolyBase loads are limited to rows smaller than 1 MB. che non possono essere caricate in VARCHR(MAX), NVARCHAR(MAX), or VARBINARY(MAX).They can't load to VARCHR(MAX), NVARCHAR(MAX), or VARBINARY(MAX). Per altre informazioni, vedere Limiti di capacità di SQL Data Warehouse.For more information, see SQL Data Warehouse service capacity limits.

Quando i dati di origine hanno righe di dimensioni superiori a 1 MB, è consigliabile suddividere verticalmente le tabelle di origine in tabelle più piccole.When your source data has rows greater than 1 MB, you might want to vertically split the source tables into several small ones. Assicurarsi che le dimensioni massime di ogni riga non superino il limite previsto.Make sure that the largest size of each row doesn't 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 by using PolyBase and merged together in Azure SQL Data Warehouse.

Classe di risorse di SQL Data WarehouseSQL Data Warehouse resource class

Per ottenere la migliore velocità effettiva possibile, assegnare una classe di risorse più ampia all'utente che carica i dati in SQL Data Warehouse tramite PolyBase.To achieve the best possible throughput, assign a larger resource class to the user that loads data into SQL Data Warehouse via PolyBase.

tableName in Azure SQL Data WarehousetableName in Azure SQL Data Warehouse

La tabella seguente fornisce alcuni esempi di come specificare la proprietà tableName nel set di dati JSON,The following table gives examples of how to specify the tableName property in the JSON dataset. mostrando diverse combinazioni di nomi di schema e di tabella.It shows several combinations of schema and table names.

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, il problema potrebbe essere costituito dal valore specificato per la proprietà tableName.If you see the following error, the problem might be the value you specified for the tableName property. Per informazioni sul modo corretto di specificare i valori per la proprietà JSON tableName, vedere la tabella precedente.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

Colonne con valori predefinitiColumns with default values

Attualmente, la funzionalità PolyBase in Data Factory accetta solo lo stesso numero di colonne disponibili nella tabella di destinazione.Currently, the PolyBase feature in Data Factory accepts only the same number of columns as in the target table. Nel caso di una tabella con quattro colonne di cui una definita con un valore predefinito, ad esempio,An example is a table with four columns where one of them is defined with a default value. i dati di input devono comunque contenere quattro colonne.The input data still needs to have four columns. Un set di dati di input con tre colonne restituisce un errore simile al messaggio seguente: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.

Il valore NULL è una forma speciale di valore predefinito.The NULL value is a special form of the default value. Se la colonna ammette valori Null, i dati di input nel BLOB per tale colonna possono essere vuoti,If the column is nullable, the input data in the blob for that column might be empty. ma non possono essere mancanti dal set di dati di input.But it can't be missing from the input dataset. PolyBase inserisce NULL per i valori mancanti in Azure SQL Data Warehouse.PolyBase inserts NULL for missing values in 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 da o 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 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. 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 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 provvisorio 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 Archivi dati e formati supportati.For a list of data stores supported as sources and sinks by Copy Activity in Azure Data Factory, see supported data stores and formats.