Copiare e trasformare i dati in Azure SQL Data Warehouse tramite Azure Data FactoryCopy and transform data in 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 e usare il flusso di dati per trasformare i dati in 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. Per altre informazioni su Azure Data Factory, vedere l'articolo introduttivo.To learn about Azure Data Factory, read the introductory article.

Funzionalità supportateSupported capabilities

Questo connettore Azure SQL Data Warehouse è supportato per le attività seguenti:This Azure SQL Data Warehouse connector is supported for the following activities:

Per l'attività di copia, questo connettore Azure SQL Data Warehouse supporta le funzioni seguenti:For Copy activity, 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à gestite per le risorse di Azure.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.
  • 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

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.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. 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.If you copy data by using a self-hosted integration runtime, configure the Azure SQL server firewall to allow the appropriate IP range. Questo intervallo include l'indirizzo IP del computer usato per connettersi al database SQL di Azure.This range includes the machine's IP that is used to connect to Azure SQL Database.

Inizia oggi stessoGet started

Suggerimento

Per ottenere prestazioni ottimali, usare PolyBase per caricare i dati in Azure SQL Data Warehouse.To achieve best performance, use PolyBase to load data into Azure SQL Data Warehouse. Vedere la sezione Usare PolyBase per caricare dati in Azure SQL Data Warehouse per i dettagli.The Use PolyBase to load data into Azure SQL Data Warehouse section has details. 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.

È possibile usare l'attività di copia con una pipeline tramite uno degli strumenti o degli SDK seguenti.You can use one of the following tools or SDKs to use the copy activity with a pipeline. Per istruzioni dettagliate, selezionare un collegamento:Select a link for step-by-step instructions:

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 DescriptionDescription 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 archiviare la chiave in modo sicuro in Data Factory.Mark this field as a SecureString to store it securely in Data Factory. È anche possibile inserire la password/chiave entità servizio in Azure Key Vault e, se si tratta dell'autenticazione SQL, estrarre la configurazione password dalla stringa di connessione.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. Vedere l'esempio JSON sotto la tabella e l'articolo Store credentials in Azure Key Vault (Archiviare le credenziali in Azure Key Vault) per altri dettagli.See the JSON example below the table and Store credentials in Azure Key Vault article with more details.
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 diversamente specificato, viene usato il runtime di integrazione di Azure predefinito.If not specified, it uses the default Azure Integration Runtime. NoNo

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:

Suggerimento

Se viene restituito l'errore con codice "UserErrorFailedToConnectToSqlServer" e un messaggio quale "Il limite di sessioni per il database è XXX ed è stato raggiunto.", aggiungere Pooling=false alla stringa di connessione e riprovare.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.

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

Password in 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"
        }
    }
}

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 al gruppo con identità gestita un ruolo di amministratore, ignorare i passaggi 3 e 4.If you grant the group with managed identity 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 riportato di seguito oppure fare riferimento a più opzioni.Run the following code, or refer to more options here. Se si desidera utilizzare la polibase per caricare i dati, acquisire informazioni sull' autorizzazione necessariaper il database.If you want to use PolyBase to load the data, learn the required database permission.

    EXEC sp_addrolemember db_owner, [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 di identità gestite per le risorse di AzureManaged identities for Azure resources authentication

Una data factory può essere associata a un'identità gestita per le risorse di Azure, che rappresenta la factory specifica.A data factory can be associated with a managed identity for Azure resources that represents the specific factory. È possibile usare questa identità gestita per l'autenticazione Azure SQL Data Warehouse.You can use this managed 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.

Per utilizzare l'autenticazione di identità gestita, attenersi alla seguente procedura:To use managed identity authentication, follow these steps:

  1. 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 al gruppo con identità gestita un ruolo di amministratore, ignorare i passaggi 3 e 4.If you grant the group with managed identity an admin role, skip steps 3 and 4. L'amministratore avrà accesso completo al database.The administrator will have full access to the database.

  2. Creare utenti di database indipendente per l'identità gestita del data factory.Create contained database users for the Data Factory Managed Identity. 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 Data Factory name] FROM EXTERNAL PROVIDER;
    
  3. Concedere le autorizzazioni necessarie per la data factory identità gestita come si fa normalmente per gli utenti SQL e altri.Grant the Data Factory Managed Identity needed permissions as you normally do for SQL users and others. Eseguire il codice riportato di seguito oppure fare riferimento a più opzioni.Run the following code, or refer to more options here. Se si desidera utilizzare la polibase per caricare i dati, acquisire informazioni sull' autorizzazione necessariaper il database.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. 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: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"
        }
    }
}

Proprietà del 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.

Per Azure SQL Data Warehouse DataSet sono supportate le proprietà seguenti:The following properties are supported for Azure SQL Data Warehouse dataset:

ProprietàProperty DescriptionDescription 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
schemaschema Nome dello schema.Name of the schema. No per l'origine, Sì per il sinkNo for source, Yes for sink
tabletable Nome della tabella o della vista.Name of the table/view. No per l'origine, Sì per il sinkNo for source, Yes for sink
tableNametableName Nome della tabella o della vista con schema.Name of the table/view with schema. Questa proprietà è supportata per compatibilità con le versioni precedenti.This property is supported for backward compatibility. Per il nuovo carico di lavoro, usare schema e table.For new workload, use schema and table. No per l'origine, Sì per il sinkNo for source, Yes for sink

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"
        },
        "schema": [ < physical schema, optional, retrievable during authoring > ],
        "typeProperties": {
            "schema": "<schema_name>",
            "table": "<table_name>"
        }
    }
}

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 DescriptionDescription 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. NoNo
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. NoNo
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.
NoNo

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.

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 DescriptionDescription 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).
NoNo
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. NoNo
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.
NoNo
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.
NoNo
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).

NoNo
writeBatchSizewriteBatchSize Numero di righe da inserire nella tabella SQL per batch.Number of rows to inserts into the SQL table per batch. 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). Per impostazione predefinita, Data Factory determina in modo dinamico le dimensioni del batch appropriate in base alle dimensioni della riga.By default, Data Factory dynamically determines the appropriate batch size based on the row size.
NoNo
writeBatchTimeoutwriteBatchTimeout Tempo di attesa per il completamento dell'operazione di inserimento batch prima del timeout. Si applica solo quando la polibase non viene utilizzata.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).
NoNo
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. NoNo
tableOptiontableOption Specifica se creare automaticamente la tabella di sink se non esiste in base allo schema di origine.Specifies whether to automatically create the sink table if not exists based on the source schema. La creazione automatica della tabella non è supportata quando la copia di gestione temporanea è configurata nell'attività di copia.Auto table creation is not supported when staged copy is configured in copy activity. I valori consentiti sono: none (impostazione predefinita), autoCreate.Allowed values are: none (default), autoCreate. NoNo
disableMetricsCollectiondisableMetricsCollection Data Factory raccoglie le metriche, ad esempio SQL Data Warehouse DWU per l'ottimizzazione delle prestazioni di copia e consigli.Data Factory collects metrics such as SQL Data Warehouse DWUs for copy performance optimization and recommendations. Se si è interessati a questo comportamento, specificare true per disattivarlo.If you are concerned with this behavior, specify true to turn it off. No (il valore predefinito è false)No (default is false)

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. 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 i dati di origine si trova in un BLOB di Azure, Azure Data Lake storage Gen1 o Azure Data Lake storage Gen2e il formato è compatibile con la polibase, è possibile usare l'attività di copia per richiamare direttamente la polibase per consentire Azure SQL data warehouse estrarre i dati dall'origine.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. 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.

Suggerimento

Altre informazioni sulle procedure consigliate per l'uso di polibase.Learn more on Best practices for using PolyBase.

Copia diretta tramite PolyBaseDirect copy by using PolyBase

SQL Data Warehouse polibase supporta direttamente BLOB, Azure Data Lake Storage Gen1 e Azure Data Lake Storage Gen2 di Azure.SQL Data Warehouse PolyBase directly supports Azure Blob, Azure Data Lake Storage Gen1 and Azure Data Lake Storage Gen2. Se i dati di origine soddisfano i criteri descritti in questa sezione, usare la polibase per copiare direttamente dall'archivio dati di origine a 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. In caso contrario, usare la copia di staging tramite PolyBase.Otherwise, use Staged copy by using PolyBase.

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 servizio collegato di origine è con i tipi e i metodi di autenticazione seguenti:The source linked service is with the following types and authentication methods:

    Tipo di archivio dati di origine supportatoSupported source data store type Tipo di autenticazione di origine supportatoSupported source authentication type
    BLOB di AzureAzure Blob Autenticazione con chiave dell'account, autenticazione di identità gestitaAccount key authentication, managed identity authentication
    Azure Data Lake Storage Gen1Azure Data Lake Storage Gen1 Autenticazione di un'entità servizioService principal authentication
    Azure Data Lake Storage Gen2Azure Data Lake Storage Gen2 Autenticazione con chiave dell'account, autenticazione di identità gestitaAccount key authentication, managed identity authentication

    Importante

    Se l'archiviazione di Azure è configurata con l'endpoint del servizio VNet, è necessario usare l'autenticazione di identità gestita. vedere l' effetto dell'uso di endpoint del servizio VNet con archiviazione di Azure.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. Per informazioni sulle configurazioni necessarie, vedere la sezione Data Factory dall' autenticazione di identità gestita da BLOB di Azure e dall' autenticazione Azure Data Lake storage Gen2 gestita , rispettivamente.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. Il formato dei dati di origine è di parquet, ORCo testo delimitato, con le configurazioni seguenti:The source data format is of Parquet, ORC, or Delimited text, with the following configurations:

    1. Il percorso della cartella non contiene il filtro con caratteri jolly.Folder path doesn't contain wildcard filter.
    2. Il nome file è vuoto o punta a un singolo file.File name is empty, or points to a single file. Se si specifica il nome del file con caratteri jolly nell'attività di copia, è possibile * o *.*.If you specify wildcard file name in copy activity, it can only be * or *.*.
    3. rowDelimiter è default, \n, \r\n o.rowDelimiter is default, \n, \r\n, or \r.
    4. nullValue viene lasciato come predefinito o è impostato su una stringa vuota ("") e treatEmptyAsNull viene lasciato come predefinito o impostato su true.nullValue is left as default or set to empty string (""), and treatEmptyAsNull is left as default or set to true.
    5. encodingName viene lasciato come predefinito o impostato su UTF-8.encodingName is left as default or set to utf-8.
    6. quoteChar, escapeChare skipLineCount non sono specificati.quoteChar, escapeChar, and skipLineCount aren't specified. La riga di intestazione Skip support, che può essere configurata come firstRowAsHeader in ADF.PolyBase support skip header row, which can be configured as firstRowAsHeader in ADF.
    7. compression può essere no compression, GZip o Deflate.compression can be no compression, GZip, or Deflate.
  3. Se l'origine è una cartella, recursive nell'attività di copia deve essere impostata su true.If your source is a folder, recursive in copy activity must be set to true.

Nota

Se l'origine è una cartella, Nota: polibase recupera i file dalla cartella e tutte le relative sottocartelle e non recupera i dati dai file per i quali il nome del file inizia con una sottolineatura () o un punto (.), come descritto qui-argomento della posizione.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
            }
        }
    }
]

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 di archiviazione BLOB di Azure che fa riferimento all'account di archiviazione di Azure con l'archivio BLOB provvisorio.To use this feature, create an Azure Blob Storage linked service that refers to the Azure storage account with the interim blob storage. Specificare quindi 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.

Importante

Se l'archiviazione di Azure di staging è configurata con l'endpoint del servizio VNet, è necessario usare l'autenticazione di identità gestita. vedere l' effetto dell'uso degli endpoint di servizio VNet con archiviazione di Azure.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. Informazioni sulle configurazioni richieste in Data Factory dall' autenticazione di identità gestita da BLOB di Azure.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"
                }
            }
        }
    }
]

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. Non può essere usato per il caricamento in VARCHR (MAX), NVARCHAR (MAX) o VARBINARY (MAX).It cannot be used to 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.

In alternativa, per i dati con colonne di questo tipo, è possibile usare l'opzione non di base per caricare i dati usando ADF, disattivando l'impostazione "Consenti polibase".Alternatively, for data with such wide columns, you can use non-PolyBase to load the data using ADF, by turning off "allow PolyBase" setting.

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.

Risoluzione dei problemi di PolyBasePolyBase troubleshooting

Caricamento in una colonna decimaleLoading to Decimal column

Se i dati di origine sono in formato testo o in altri archivi compatibili non di base (usando la copia di staging e la polibase) e contiene un valore vuoto da caricare in SQL Data Warehouse colonna decimale, è possibile che venga raggiunto l'errore seguente: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.....

La soluzione consiste nell'deselezionare l'opzione "Usa il tipo predefinito" (false) nelle impostazioni di base del sink dell'attività di copia->.The solution is to unselect "Use type default" option (as false) in copy activity sink -> PolyBase settings. "USE_TYPE_DEFAULT" è una configurazione nativa di base, che specifica come gestire i valori mancanti in file di testo delimitati quando la polibase recupera i dati dal file di testo."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.

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 delle proprietà del flusso di datiMapping data flow properties

Per informazioni dettagliate, vedere trasformazione origine e trasformazione sink nel flusso di dati del mapping.Learn details from source transformation and sink transformation in mapping data flow.

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.

Suggerimento

Fare riferimento ai tipi di dati della tabella in Azure SQL data warehouse articolo sui tipi di dati supportati da SQL DW e sulle soluzioni alternative per quelli non supportati.Refer to Table data types in Azure SQL Data Warehouse article on SQL DW supported data types and the workarounds for unsupported ones.

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 Data e oraDateTime
DateTimeDatetime Data e oraDateTime
datetime2datetime2 Data e oraDateTime
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 SingoloSingle
rowversionrowversion Byte[]Byte[]
smalldatetimesmalldatetime Data e oraDateTime
smallintsmallint Int16Int16
smallmoneysmallmoney DECIMALDecimal
timetime Intervallo di tempoTimeSpan
tinyinttinyint ByteByte
uniqueidentifieruniqueidentifier GUIDGuid
varbinaryvarbinary Byte[]Byte[]
varcharvarchar String, Char[]String, Char[]

Proprietà attività di ricercaLookup activity properties

Per informazioni dettagliate sulle proprietà, controllare l' attività di ricerca.To learn details about the properties, check Lookup activity.

Proprietà dell'attività GetMetadataGetMetadata activity properties

Per informazioni dettagliate sulle proprietà, controllare l' attività GetMetadataTo learn details about the properties, check GetMetadata activity

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.