Copiare e trasformare i dati in Azure Synapse Analytics usando le pipeline di Azure Data Factory o Synapse

SI APPLICA A: Azure Data Factory Azure Synapse Analytics

Questo articolo illustra come usare l'attività di copia nelle pipeline di Azure Data Factory o Synapse per copiare dati da e in Azure Synapse Analytics, e usare Flusso di dati per trasformare i dati in Azure Data Lake Storage Gen2. Per altre informazioni su Azure Data Factory, vedere l'articolo introduttivo.

Funzionalità supportate

Questo connettore di Azure Synapse Analytics è supportato per le funzionalità seguenti:

Funzionalità supportate	IR	Endpoint privato gestito
Attività di copia (origine/sink)	7.3	✓
Flusso di dati di mapping (origine/sink)	1	✓
Attività Lookup	7.3	✓
Attività GetMetadata	7.3	✓
Attività script	7.3	✓
Attività stored procedure	7.3	✓

① Runtime di integrazione di Azure ② Runtime di integrazione self-hosted

Per l'attività di copia, questo connettore di Azure Synapse Analytics supporta le funzioni seguenti:

• La copia dei dati tramite l'autenticazione SQL e l'autenticazione del token dell'applicazione Microsoft Entra con un'entità servizio o identità gestite per le risorse di Azure.
• Come origine, il recupero di dati tramite query SQL o stored procedure. È anche possibile scegliere di eseguire la copia parallela da un'origine di Azure Synapse Analytics. Per informazioni dettagliate, vedere la sezione Copia parallela da Azure Synapse Analytics.
• Come sink, caricare i dati usando l'istruzione COPY o PolyBase o l'inserimento bulk. È consigliabile usare l'istruzione COPY o PolyBase per migliorare le prestazioni di copia. Il connettore supporta anche la creazione automatica della tabella di destinazione con DISTRIBUTION = ROUND_ROBIN se non esiste in base allo schema di origine.

Operazioni preliminari

Per eseguire l'attività di copia con una pipeline, è possibile usare uno degli strumenti o SDK seguenti:

• Strumento Copia dati
• Il portale di Azure
• .NET SDK
• SDK di Python
• Azure PowerShell
• API REST
• Modello di Azure Resource Manager

Creare un servizio collegato Azure Synapse Analytics usando l’interfaccia utente

Usare la procedura seguente per creare un servizio collegato di Azure Synapse Analytics nell'interfaccia utente del portale di Azure.

1. Passare alla scheda Gestisci nell'area di lavoro di Azure Data Factory o Synapse e selezionare Servizi collegati, quindi fare clic su Nuovo:

   • Azure Data Factory
   • Azure Synapse

   

2. Cercare Synapse e selezionare il connettore Azure Synapse Analytics.

   

3. Configurare i dettagli del servizio, testare la connessione e creare il nuovo servizio collegato.

   

Dettagli di configurazione del connettore

Le sezioni seguenti forniscono informazioni dettagliate sulle proprietà che definiscono entità della pipeline di Data Factory e Synapse specifiche per un connettore di Azure Synapse Analytics.

Proprietà del servizio collegato

La versione consigliata del connettore Azure Synapse Analytics supporta TLS 1.3. Fare riferimento a questa sezione per aggiornare la versione del connettore Azure Synapse Analytics da quella Legacy. Per informazioni dettagliate sulla proprietà, vedere le sezioni corrispondenti.

• Versione consigliata
• Versione legacy

Versione consigliata

Queste proprietà generiche sono supportate per un servizio collegato di Azure Synapse Analytics quando si applica la versione consigliata:

Proprietà	Descrizione	Richiesto
type	La proprietà type deve essere impostata su AzureSqlDW.	Sì
server	Nome o indirizzo di rete dell'istanza di SQL Server a cui connettersi.	Sì
database	Nome del database.	Sì
authenticationType	Tipo utilizzato per l'autenticazione. I valori consentiti sono SQL (impostazione predefinita), ServicePrincipal, SystemAssignedManagedIdentity, UserAssignedManagedIdentity. Passare alla sezione relativa all'autenticazione in base a proprietà e prerequisiti specifici.	Sì
crittografare	Indicare se la crittografia TLS è necessaria per tutti i dati inviati tra client e server. Opzioni: obbligatorio (per true, impostazione predefinita)/opzionale (per false)/strict.	No
trustServerCertificate	Indicare se il canale verrà crittografato bypassando la catena di certificati per convalidare l'attendibilità.	No
hostNameInCertificate	Nome host da usare quando viene convalidato il certificato del server per la connessione. Se non è specificato, per la convalida del certificato viene utilizzato il nome del server.	No
connectVia	Runtime di integrazione da usare per la connessione all'archivio dati. È 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). Se non specificato, viene usato il runtime di integrazione di Azure predefinito.	No

Per altre proprietà di connessione, vedere la tabella seguente:

Proprietà	Descrizione	Richiesto
applicationIntent	Il tipo di carico di lavoro dell'applicazione in caso di connessione a un server. I valori consentiti sono ReadOnly e ReadWrite.	No
connectTimeout	Tempo di attesa (in secondi) per una connessione al server prima della conclusione del tentativo e la generazione di un errore.	No
connectRetryCount	Numero di riconnessioni tentate dopo l'identificazione di un errore di connessione inattiva. Il valore deve essere un numero intero compreso tra 0 e 255.	No
connectRetryInterval	Intervallo di tempo, (espresso in secondi) tra ogni tentativo di riconnessione dopo l'identificazione di un errore di connessione inattiva. Il valore deve essere un numero intero compreso tra 1 e 60.	No
loadBalanceTimeout	Tempo minimo (in secondi) in cui la connessione rimane attiva nel pool di connessione prima di essere eliminata definitivamente.	No
commandTimeout	Tempo di attesa predefinito (in secondi) prima della conclusione del tentativo di esecuzione di un comando e della generazione di un errore.	No
integratedSecurity	I valori consentiti sono true o false. Quando si specifica false, indicare se userName e password sono specificati nella connessione. Quando si specifica true, indica se le credenziali dell'account di Windows corrente vengono usate per l'autenticazione.	No
failoverPartner	Nome o indirizzo di rete del server partner a cui connettersi se il server primario è inattivo.	No
maxPoolSize	Numero massimo di connessioni consentite nel pool di connessioni per la connessione specifica.	No
minPoolSize	Numero minimo di connessioni consentite nel pool di connessioni per la connessione specifica.	No
multipleActiveResultSets	I valori consentiti sono true o false. Quando si specifica true, un'applicazione può gestire più insiemi di risultati attivi (MARS). Quando si specifica false, un'applicazione deve prima elaborare o annullare tutti gli insiemi di risultati da un batch per poter eseguire altri batch in tale connessione.	No
multiSubnetFailover	I valori consentiti sono true o false. Se l'applicazione si connette a un gruppo di disponibilità (AG) AlwaysOn in subnet diverse, l'impostazione di questa proprietà su true garantisce una maggiore velocità di rilevamento e connessione al server attualmente attivo.	No
packetSize	Dimensioni in byte dei pacchetti di rete usati per comunicare con un'istanza del server.	No
pooling	I valori consentiti sono true o false. Quando si specifica true, la connessione sarà in pool. Quando si specifica false, la connessione verrà aperta in modo esplicito ogni volta che è richiesta la connessione.	No

Autenticazione SQL

Per usare l’autenticazione SQL, oltre alle proprietà generiche descritte nella sezione precedente, specificare le proprietà seguenti:

Proprietà	Descrizione	Richiesto
userName	Nome utente utilizzato per connettersi al server.	Sì
password	Password per il nome utente. Contrassegnare questo campo come SecureString per archiviarlo in modo sicuro. In alternativa, fare riferimento a un segreto archiviato in Azure Key Vault.	Sì

Esempio: uso dell'autenticazione di SQL

{
    "name": "AzureSqlDWLinkedService",
    "properties": {
        "type": "AzureSqlDW",
        "typeProperties": {
            "server": "<name or network address of the SQL server instance>",
            "database": "<database name>",
            "encrypt": "<encrypt>",
            "trustServerCertificate": false,
            "authenticationType": "SQL",
            "userName": "<user name>",
            "password": {
                "type": "SecureString",
                "value": "<password>"
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Esempio: password in Azure Key Vault

{
    "name": "AzureSqlDWLinkedService",
    "properties": {
        "type": "AzureSqlDW",
        "typeProperties": {
            "server": "<name or network address of the SQL server instance>",
            "database": "<database name>",
            "encrypt": "<encrypt>",
            "trustServerCertificate": false,
            "authenticationType": "SQL",
            "userName": "<user name>",
            "password": {
                "type": "AzureKeyVaultSecret",
                "store": {
                    "referenceName": "<Azure Key Vault linked service name>",
                    "type": "LinkedServiceReference"
                },
                "secretName": "<secretName>"
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Autenticazione dell'entità servizio

Per usare l'autenticazione dell'entità servizio, oltre alle proprietà generiche descritte nella sezione precedente, specificare le proprietà seguenti:

Proprietà	Descrizione	Richiesto
servicePrincipalId	Specificare l'ID client dell'applicazione.	Sì
servicePrincipalCredential	Credenziali dell'entità servizio. Specificare la chiave dell'applicazione. Contrassegnare questo campo come SecureString per archiviarlo in modo sicuro, oppure fare riferimento a un segreto archiviato in Azure Key Vault.	Sì
tenant	Specificare le informazioni sul tenant (nome di dominio o ID tenant) in cui si trova l'applicazione. È possibile recuperarlo passando il cursore del mouse sull'angolo superiore destro del portale di Azure.	Sì
azureCloudType	Per l'autenticazione dell'entità servizio, specificare il tipo di ambiente cloud di Azure in cui è registrata l'applicazione Microsoft Entra. I valori consentiti sono AzurePublic, AzureChina, AzureUsGovernment e AzureGermany. Per impostazione predefinita, viene usato l'ambiente cloud della data factory o della pipeline Synapse.	No

È anche necessario seguire la procedura seguente:

1. Creare un'applicazione Microsoft Entra dal portale di Azure. Prendere nota del nome dell'applicazione e dei valori seguenti che definiscono il servizio collegato:

   • ID applicazione
   • Chiave applicazione
   • ID tenant

2. Effettuare il provisioning di un amministratore di Microsoft Entra per il server nel portale di Azure, se non è già stato fatto. L'amministratore di Microsoft Entra può essere un utente di Microsoft Entra o un gruppo Microsoft Entra. Se si concede al gruppo con identità gestita un ruolo di amministratore, ignorare i passaggi 3 e 4. L'amministratore avrà accesso completo al database.

3. Creare utenti del database indipendente per l'entità servizio. Connettersi al data warehouse da o in cui si vogliono copiare i dati usando strumenti come SSMS, con un'identità di Microsoft Entra che abbia almeno l'autorizzazione ALTER ANY USER. Eseguire il codice T-SQL seguente:

   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. Eseguire il codice seguente o vedere altre opzioni qui. Se si vuole usare PolyBase per caricare i dati, vedere le informazioni sull'autorizzazione necessaria per il database.

   EXEC sp_addrolemember db_owner, [your application name];
   

5. Configurare un servizio collegato di Azure Synapse Analytics in un'area di lavoro di Azure Data Factory o Synapse.

Esempio di servizio collegato tramite l'autenticazione basata su entità servizio

{
    "name": "AzureSqlDWLinkedService",
    "properties": {
        "type": "AzureSqlDW",
        "typeProperties": {
            "connectionString": "Server=tcp:<servername>.database.windows.net,1433;Database=<databasename>;Connection Timeout=30",
            "servicePrincipalId": "<service principal id>",
            "servicePrincipalCredential": {
                "type": "SecureString",
                "value": "<application key>"
            },
            "tenant": "<tenant info, e.g. microsoft.onmicrosoft.com>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Identità gestite assegnate dal sistema per l'autenticazione delle risorse di Azure

Una data factory o un'area di lavoro di Synapse può essere associata a un'identità gestita assegnata dal sistema per le risorse di Azure che rappresenta la risorsa. È possibile usare questa identità gestita per l'autenticazione di Azure Synapse Analytics. La risorsa designata può accedere ai dati e copiarli da o nel data warehouse tramite questa identità.

Per usare l'autenticazione dell'identità gestita assegnata dal sistema, specificare le proprietà generiche descritte nella sezione precedente e seguire questa procedura.

1. Effettuare il provisioning di un amministratore di Microsoft Entra per il server nel portale di Azure, se non è già stato fatto. L'amministratore di Microsoft Entra può essere un utente di Microsoft Entra o un gruppo Microsoft Entra. Se si concede al gruppo un ruolo di amministratore con identità gestita assegnata dal sistema, ignorare i passaggi 3 e 4. L'amministratore avrà accesso completo al database.

2. Creare utenti di database indipendenti per l'identità gestita assegnata dal sistema. Connettersi al data warehouse da o in cui si vogliono copiare i dati usando strumenti come SSMS, con un'identità di Microsoft Entra che abbia almeno l'autorizzazione ALTER ANY USER. Eseguire il comando in T-SQL seguente.

   CREATE USER [your_resource_name] FROM EXTERNAL PROVIDER;
   

3. Concedere le autorizzazioni necessarie per l'identità gestita assegnata dal sistema come si fa normalmente per utenti SQL e altri utenti. Eseguire il codice seguente o vedere altre opzioni qui. Se si vuole usare PolyBase per caricare i dati, vedere le informazioni sull'autorizzazione necessaria per il database.

   EXEC sp_addrolemember db_owner, [your_resource_name];
   

4. Configurare un servizio collegato Azure Synapse Analytics.

Esempio:

{
    "name": "AzureSqlDWLinkedService",
    "properties": {
        "type": "AzureSqlDW",
        "typeProperties": {
            "server": "<name or network address of the SQL server instance>",
            "database": "<database name>",
            "encrypt": "<encrypt>",
            "trustServerCertificate": false,
            "authenticationType": "SystemAssignedManagedIdentity"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Autenticazione dell'identità gestita assegnata dall'utente

Una data factory o un'area di lavoro di Synapse può essere associata a un'identità gestita assegnata dall'utente che rappresenta la risorsa. È possibile usare questa identità gestita per l'autenticazione di Azure Synapse Analytics. La risorsa designata può accedere ai dati e copiarli da o nel data warehouse tramite questa identità.

Per usare l'autenticazione dell'identità gestita assegnata dall'utente, oltre alle proprietà generiche descritte nella sezione precedente, specificare le proprietà seguenti:

Proprietà	Descrizione	Richiesto
credentials	Specificare l'identità gestita assegnata dall'utente come oggetto credenziale.	Sì

È anche necessario seguire la procedura seguente:

1. Effettuare il provisioning di un amministratore di Microsoft Entra per il server nel portale di Azure, se non è già stato fatto. L'amministratore di Microsoft Entra può essere un utente di Microsoft Entra o un gruppo Microsoft Entra. Se si concede al gruppo un ruolo di amministratore con identità gestita assegnata dall'utente, ignorare i passaggi 3. L'amministratore avrà accesso completo al database.

2. Creare utenti di database indipendenti per l'identità gestita assegnata dall'utente. Connettersi al data warehouse da o in cui si vogliono copiare i dati usando strumenti come SSMS, con un'identità di Microsoft Entra che abbia almeno l'autorizzazione ALTER ANY USER. Eseguire il comando in T-SQL seguente.

   CREATE USER [your_resource_name] FROM EXTERNAL PROVIDER;
   

3. Creare una o più identità gestite assegnate dall'utente e concedere le autorizzazioni necessarie per l'identità gestita assegnata dall'utente, come normalmente si fa per utenti SQL e altri utenti. Eseguire il codice seguente o vedere altre opzioni qui. Se si vuole usare PolyBase per caricare i dati, vedere le informazioni sull'autorizzazione necessaria per il database.

   EXEC sp_addrolemember db_owner, [your_resource_name];
   

4. Assegnare una o più identità gestite assegnate dall'utente alla data factory e creare le credenziali per ogni identità gestita assegnata dall'utente.

5. Configurare un servizio collegato Azure Synapse Analytics.

Esempio

{
    "name": "AzureSqlDWLinkedService",
    "properties": {
        "type": "AzureSqlDW",
        "typeProperties": {
            "server": "<name or network address of the SQL server instance>",
            "database": "<database name>",
            "encrypt": "<encrypt>",
            "trustServerCertificate": false,
            "authenticationType": "UserAssignedManagedIdentity",
            "credential": {
                "referenceName": "credential1",
                "type": "CredentialReference"
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Versione legacy

Queste proprietà generiche sono supportate per un servizio collegato di Azure Synapse Analytics quando si applica la versione legacy:

Proprietà	Descrizione	Richiesto
type	La proprietà type deve essere impostata su AzureSqlDW.	Sì
connectionString	Specificare le informazioni necessarie per connettersi all'istanza di Azure Synapse Analytics per la proprietà connectionString. Contrassegnare questo campo come SecureString per archiviarlo in modo sicuro. È 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. Vedere l'articolo Archiviare le credenziali in Azure Key Vault con altri dettagli.	Sì
connectVia	Runtime di integrazione da usare per la connessione all'archivio dati. È 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). Se non specificato, viene usato il runtime di integrazione di Azure predefinito.	No

Per altri tipi di autenticazione, vedere le sezioni seguenti relative rispettivamente a proprietà e prerequisiti specifici:

• Autenticazione SQL per la versione legacy
• Autenticazione dell'entità servizio per la versione legacy
• Autenticazione dell'identità gestita assegnata dal sistema per la versione legacy
• Autenticazione dell'identità gestita assegnata dall'utente per la versione legacy

Autenticazione SQL per la versione legacy

Per usare l'autenticazione SQL, specificare le proprietà generiche descritte nella sezione precedente.

Autenticazione dell'entità servizio per la versione legacy

Per usare l'autenticazione dell'entità servizio, oltre alle proprietà generiche descritte nella sezione precedente, specificare le proprietà seguenti:

Proprietà	Descrizione	Richiesto
servicePrincipalId	Specificare l'ID client dell'applicazione.	Sì
servicePrincipalKey	Specificare la chiave dell'applicazione. Contrassegnare questo campo come SecureString per archiviarlo in modo sicuro, oppure fare riferimento a un segreto archiviato in Azure Key Vault.	Sì
tenant	Specificare le informazioni sul tenant, ad esempio nome di dominio o ID tenant, in cui si trova l'applicazione. Recuperarlo passando il cursore del mouse sull'angolo superiore destro del portale di Azure.	Sì
azureCloudType	Per l'autenticazione dell'entità servizio, specificare il tipo di ambiente cloud di Azure in cui è registrata l'applicazione Microsoft Entra. I valori consentiti sono AzurePublic, AzureChina, AzureUsGovernment e AzureGermany. Per impostazione predefinita, viene usato l'ambiente cloud della data factory o della pipeline Synapse.	No

È anche necessario seguire la procedura descritta in Autenticazione dell'entità servizio per concedere l'autorizzazione corrispondente.

Autenticazione dell'identità gestita assegnata dal sistema per la versione legacy

Per usare l'autenticazione dell'identità gestita assegnata dal sistema, seguire lo stesso passaggio per la versione consigliata in Autenticazione identità gestita assegnata dal sistema.

Autenticazione dell'identità gestita assegnata dall'utente per la versione legacy

Per usare l'autenticazione dell'identità gestita assegnata dall'utente, seguire lo stesso passaggio per la versione consigliata in Autenticazione identità gestita assegnata dall'utente.

Proprietà del set di dati

Per un elenco completo delle sezioni e delle proprietà disponibili per la definizione dei set di dati, vedere l'articolo Set di dati.

Per un set di dati di Azure Synapse Analytics sono supportate le proprietà seguenti:

Proprietà	Descrizione	Richiesto
type	La proprietà type del set di dati deve essere impostata su AzureSqlDWTable.	Sì
schema	Nome dello schema.	No per l'origine, Sì per il sink
table	Nome della tabella/vista.	No per l'origine, Sì per il sink
tableName	Nome della tabella/vista con schema. Questa proprietà è supportata per garantire la compatibilità con le versioni precedenti. Per i nuovi carichi di lavoro, usare schema e table.	No per l'origine, Sì per il sink

Esempio di proprietà dei set di dati

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

Proprietà dell'attività di copia

Per un elenco completo delle sezioni e delle proprietà disponibili per la definizione delle attività, vedere l'articolo sulle pipeline. Questa sezione presenta un elenco delle proprietà supportate dall'origine e dal sink di Azure Synapse Analytics.

Azure Synapse Analytics come origine

Per copiare dati da Azure Synapse Analytics, impostare la proprietà type nell'origine dell'attività di copia su SqlDWSource. Nella sezione source dell'attività di copia sono supportate le proprietà seguenti:

Proprietà	Descrizione	Richiesto
type	La proprietà type dell'origine dell'attività di copia deve essere impostata su SqlDWSource.	Sì
sqlReaderQuery	Usare la query SQL personalizzata per leggere i dati. Esempio: select * from MyTable.	No
sqlReaderStoredProcedureName	Nome della stored procedure che legge i dati dalla tabella di origine. L'ultima istruzione SQL deve essere un'istruzione SELECT nella stored procedure.	No
storedProcedureParameters	Parametri per la stored procedure. I valori consentiti sono coppie nome-valore. I nomi e le maiuscole e minuscole dei parametri devono corrispondere ai nomi e alle maiuscole e minuscole dei parametri della stored procedure.	No
isolationLevel	Specifica il comportamento di blocco della transazione per l'origine SQL. Valori consentiti: ReadCommitted, ReadUncommitted, RepeatableRead, Serializable e Snapshot. Se non è specificato, viene utilizzato il livello di isolamento predefinito del database. Per altre informazioni, vedere system.data.isolationlevel.	No
partitionOptions	Specifica le opzioni di partizionamento dei dati usate per caricare i dati da Azure Synapse Analytics. Valori consentiti: None (predefinito), PhysicalPartitionsOfTable e DynamicRange. Quando è abilitata un'opzione di partizione (diversa da None), il grado di parallelismo per caricare simultaneamente i dati da Azure Synapse Analytics è controllato dall'impostazione parallelCopies nell'attività di copia.	No
partitionSettings	Specifica il gruppo di impostazioni per il partizionamento dei dati. Applicare quando l'opzione di partizione non è None.	No
In partitionSettings:
partitionColumnName	Specificare il nome della colonna di origine nel tipo integer o date/datetime type (int, smallint, bigint, date, smalldatetime, datetime, datetime2 o datetimeoffset) che verrà usata nel partizionamento per intervalli per la copia parallela. Se non specificato, l'indice o la chiave primaria della tabella vengono rilevati automaticamente e usati come colonna di partizione. Si applica quando l'opzione di partizione è DynamicRange. Se si usa una query per recuperare i dati di origine, associare ?DfDynamicRangePartitionCondition nella clausola WHERE. Per un esempio, vedere la sezione Copia parallela dal database SQL.	No
partitionUpperBound	Valore massimo della colonna di partizione per la suddivisione dell'intervallo di partizioni. Questo valore viene usato per decidere lo stride di partizione, non per filtrare le righe nella tabella. Tutte le righe nella tabella o nel risultato della query verranno partizionate e copiate. Se non specificato, l'attività Copy rileva automaticamente il valore. Si applica quando l'opzione di partizione è DynamicRange. Per un esempio, vedere la sezione Copia parallela dal database SQL.	No
partitionLowerBound	Valore minimo della colonna di partizione per la suddivisione dell'intervallo di partizioni. Questo valore viene usato per decidere lo stride di partizione, non per filtrare le righe nella tabella. Tutte le righe nella tabella o nel risultato della query verranno partizionate e copiate. Se non specificato, l'attività Copy rileva automaticamente il valore. Si applica quando l'opzione di partizione è DynamicRange. Per un esempio, vedere la sezione Copia parallela dal database SQL.	No

Tenere presente quanto segue:

• Quando si usa la stored procedure nell'origine per recuperare dati, tenere presente che se la stored procedure è progettata per restituire schemi diversi quando viene passato un valore di parametro diverso, è possibile che si verifichi un errore o un risultato imprevisto durante l'importazione dello schema dall'interfaccia utente o quando si copiano dati nel database SQL con la creazione automatica della tabella.

Esempio: uso della query SQL

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

Esempio: uso della stored procedure

"activities":[
    {
        "name": "CopyFromAzureSQLDW",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<Azure Synapse Analytics input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "SqlDWSource",
                "sqlReaderStoredProcedureName": "CopyTestSrcStoredProcedureWithParameters",
                "storedProcedureParameters": {
                    "stringData": { "value": "str3" },
                    "identifier": { "value": "$$Text.Format('{0:yyyy}', <datetime parameter>)", "type": "Int"}
                }
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

Stored procedure di esempio:

CREATE PROCEDURE CopyTestSrcStoredProcedureWithParameters
(
    @stringData varchar(20),
    @identifier int
)
AS
SET NOCOUNT ON;
BEGIN
    select *
    from dbo.UnitTestSrcTable
    where dbo.UnitTestSrcTable.stringData != stringData
    and dbo.UnitTestSrcTable.identifier != identifier
END
GO

Azure Synapse Analytics come sink

Le pipeline di Azure Data Factory e Synapse supportano tre modi per caricare i dati in Azure Synapse Analytics.

• Usare l’istruzione COPY
• Usare PolyBase
• Usare l'inserimento bulk

Il modo più rapido e scalabile per caricare i dati consiste nell'istruzione COPY o nella PolyBase.

Per copiare dati in Azure Synapse Analytics, impostare il tipo di sink nell'attività di copia su SqlDWSink. Nella sezione sink dell'attività di copia sono supportate le proprietà seguenti:

Proprietà	Descrizione	Richiesto
type	La proprietà type del sink dell'attività di copia deve essere impostata su SqlDWSink.	Sì
allowPolyBase	Indica se usare PolyBase per caricare i dati in Azure Synapse Analytics. allowCopyCommand e allowPolyBase non possono essere entrambi true. Vedere la sezione Usare PolyBase per caricare i dati in Azure Synapse Analytics per i vincoli e i dettagli. I valori consentiti sono True e False (predefinito).	No. Applicare quando si usa PolyBase.
polyBaseSettings	Gruppo di proprietà che è possibile specificare quando la proprietà allowPolybase è impostata su true.	No. Applicare quando si usa PolyBase.
allowCopyCommand	Indica se usare l’istruzione COPY per caricare i dati in Azure Synapse Analytics. allowCopyCommand e allowPolyBase non possono essere entrambi true. Per informazioni su vincoli e dettagli, vedere la sezione Usare l'istruzione COPY per caricare dati in Azure Synapse Analytics. I valori consentiti sono True e False (predefinito).	No. Applicare quando si usa COPY.
copyCommandSettings	Gruppo di proprietà che è possibile specificare quando la proprietà allowCopyCommand è impostata su TRUE.	No. Applicare quando si usa COPY.
writeBatchSize	Numero di righe da inserire nella tabella SQL per batch. Il valore consentito è integer (numero di righe). Per impostazione predefinita, il servizio determina in modo dinamico le dimensioni appropriate del batch in base alle dimensioni della riga.	No. Applicare quando si usa l'inserimento bulk.
writeBatchTimeout	Tempo di attesa per il completamento dell'operazione insert, upsert e stored procedure prima del timeout. I valori consentiti sono relativi all'intervallo di tempo. Esempio: "00:30:00" per 30 minuti. Se non si specifica alcun valore, viene utilizzato il timeout predefinito, "00:30:00".	No. Applicare quando si usa l'inserimento bulk.
preCopyScript	Specificare una query SQL per l'attività di copia da eseguire prima di scrivere i dati in Azure Synapse Analytics ad ogni esecuzione. Usare questa proprietà per pulire i dati precaricati.	No
tableOption	Specifica se creare automaticamente la tabella sink, se non esiste, in base allo schema di origine. I valori consentiti sono: none (impostazione predefinita), autoCreate.	No
disableMetricsCollection	Il servizio raccoglie metriche come le DWU di Azure Synapse Analytics per l'ottimizzazione delle prestazioni di copia e le raccomandazioni, che introducono l'accesso al database master aggiuntivo. Se questo comportamento non è desiderato, specificare true per disattivarlo.	No (il valore predefinito è false)
maxConcurrentConnections	Limite massimo di connessioni simultanee stabilite all'archivio dati durante l'esecuzione dell'attività. Specificare un valore solo quando si desidera limitare le connessioni simultanee.	No
WriteBehavior	Specificare il comportamento di scrittura per l'attività di copia per caricare i dati in Azure Synapse Analytics. Il valore consentito è Insert e Upsert. Per impostazione predefinita, il servizio usa l’operazione insert per caricare dati.	No
upsertSettings	Specificare il gruppo di impostazioni per il comportamento di scrittura. Applicare quando l'opzione WriteBehavior è Upsert.	No
In upsertSettings:
keys	Specificare i nomi colonna per l'identificazione univoca delle righe. È possibile usare una singola chiave o una serie di chiavi. Se non specificato, viene usata la chiave primaria.	No
interimSchemaName	Specificare lo schema provvisorio per la creazione di una tabella provvisoria. Nota: l'utente deve disporre dell'autorizzazione per la creazione e l'eliminazione della tabella. Per impostazione predefinita, la tabella provvisoria condividerà lo stesso schema della tabella sink.	No

Esempio 1: sink di Azure Synapse Analytics

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

Esempio 2: Upsert dei dati

"sink": {
    "type": "SqlDWSink",
    "writeBehavior": "Upsert",
    "upsertSettings": {
        "keys": [
             "<column name>"
        ],
        "interimSchemaName": "<interim schema name>"
    },
}

Copia parallela da Azure Synapse Analytics

Il connettore Azure Synapse Analytics nell'attività di copia fornisce il partizionamento dei dati predefinito per copiare i dati in parallelo. È possibile trovare le opzioni di partizionamento dei dati nella tabella Origine dell'attività di copia.

Quando si abilita la copia partizionata, l'attività di copia esegue query parallele sull'origine di Azure Synapse Analytics per caricare i dati in base alle partizioni. Il grado di parallelismo è controllato dall'impostazione parallelCopies sull'attività di copia. Se, ad esempio, si imposta parallelCopies su quattro, il servizio simultaneamente genera ed esegue quattro query in base all'opzione partizione specificata e alle impostazioni, e ogni query recupera una porzione di dati da Azure Synapse Analytics.

Si consiglia di abilitare la copia parallela con il partizionamento dei dati, specialmente quando si caricano grandi quantità di dati da Azure Synapse Analytics. Di seguito sono riportate le configurazioni consigliate per i diversi scenari: Quando si copiano dati in un archivio dati basato su file, è consigliabile scrivere in una cartella come file multipli (specificare solo il nome della cartella); in tal caso, le prestazioni risultano migliori rispetto alla scrittura in un singolo file.

Scenario	Impostazioni consigliate
Caricamento completo da una tabella di grandi dimensioni, con partizioni fisiche.	Opzione di partizione: partizioni fisiche della tabella. Durante l'esecuzione, il servizio rileva automaticamente le partizioni fisiche e copia i dati in base alle partizioni. Per controllare se la tabella contenga o meno una partizione fisica, è possibile fare riferimento a questa query.
Caricamento completo da una tabella di grandi dimensioni, senza partizioni fisiche, con una colonna integer o datetime per il partizionamento dei dati.	Opzioni di partizione: partizione a intervalli dinamici. Colonna partizione (facoltativo): specificare la colonna usata per il partizionamento dei dati. Se non specificato, viene utilizzata la colonna di indice o chiave primaria. Limite superiore partizione e limite inferiore partizione (facoltativo): specificare se si desidera determinare lo stride della partizione. Non si tratta di filtrare le righe nella tabella; tutte le righe della tabella verranno partizionate e copiate. Se non è specificato, l'attività di copia rileva automaticamente i valori. Ad esempio, se “ID” della colonna partizione include valori compresi tra 1 e 100 e si imposta come limite inferiore 20 e come limite superiore 80, con copia parallela 4, il servizio recupera i dati in base a 4 partizioni - ID nell'intervallo < = 20, [21, 50], [51, 80] e > = 81 rispettivamente.
Caricamento di notevoli quantità di dati utilizzando una query personalizzata, senza partizioni fisiche, con una colonna integer o date/datetime per il partizionamento dei dati.	Opzioni di partizione: partizione a intervalli dinamici. Query: SELECT * FROM <TableName> WHERE ?DfDynamicRangePartitionCondition AND <your_additional_where_clause>. Colonna di partizione: specificare la colonna usata per il partizionamento dei dati. Limite superiore partizione e limite inferiore partizione (facoltativo): specificare se si desidera determinare lo stride della partizione. Ciò non è utile a filtrare le righe nella tabella; tutte le righe del risultato della query verranno partizionate e copiate. Se non specificato, l'attività Copy rileva automaticamente il valore. Ad esempio, se la colonna di partizione "ID" include valori compresi tra 1 e 100 e si imposta il limite inferiore su 20 e il limite superiore su 80, con copia parallela come 4 il servizio recupera i dati per 4 partizioni - ID nell'intervallo <=20, [21, 50], [51, 80], e >=81, rispettivamente. Di seguito sono riportate altre query di esempio per diversi scenari: 1. Eseguire una query sull'intera tabella: SELECT * FROM <TableName> WHERE ?DfDynamicRangePartitionCondition 2. Eseguire una query da una tabella con selezione colonne e filtri aggiuntivi per la clausola where: SELECT <column_list> FROM <TableName> WHERE ?DfDynamicRangePartitionCondition AND <your_additional_where_clause> 3. Query con sottoquery: SELECT <column_list> FROM (<your_sub_query>) AS T WHERE ?DfDynamicRangePartitionCondition AND <your_additional_where_clause> 4. Query con partizione nella sottoquery: SELECT <column_list> FROM (SELECT <your_sub_query_column_list> FROM <TableName> WHERE ?DfDynamicRangePartitionCondition) AS T

Procedure consigliate per il caricamento di dati con opzione partizione:

1. Scegliere una colonna distintiva come colonna partizione (ad esempio, chiave primaria o chiave univoca) per evitare l'asimmetria dei dati.
2. Se la tabella include una partizione predefinita, usare l'opzione di partizione "Partizioni fisiche della tabella" per ottenere prestazioni migliori.
3. Se si usa Azure Integration Runtime per copiare i dati, è possibile impostare "Unità di integrazione dati (DIU)" (>4) perché utilizzi più risorse di calcolo. Controllare gli scenari applicabili.
4. “Grado di parallelismo copia” controlla i numeri partizione; impostando per questo numero un valore eccessivo, a volte le prestazioni si riducono. È preferibile impostare questo numero come (DIU o numero di nodi del runtime di integrazione self-hosted) * (2-4).
5. Nota: Azure Synapse Analytics può eseguire un massimo di 32 query al momento, impostando "Grado di parallelismo di copia" troppo grande può causare un problema di limitazione di Synapse.

Esempio: caricamento completo da una tabella di grandi dimensioni con partizioni fisiche

"source": {
    "type": "SqlDWSource",
    "partitionOption": "PhysicalPartitionsOfTable"
}

Esempio: query con partizione a intervalli dinamici

"source": {
    "type": "SqlDWSource",
    "query": "SELECT * FROM <TableName> WHERE ?DfDynamicRangePartitionCondition AND <your_additional_where_clause>",
    "partitionOption": "DynamicRange",
    "partitionSettings": {
        "partitionColumnName": "<partition_column_name>",
        "partitionUpperBound": "<upper_value_of_partition_column (optional) to decide the partition stride, not as data filter>",
        "partitionLowerBound": "<lower_value_of_partition_column (optional) to decide the partition stride, not as data filter>"
    }
}

Query di esempio per controllare la partizione fisica

SELECT DISTINCT s.name AS SchemaName, t.name AS TableName, c.name AS ColumnName, CASE WHEN c.name IS NULL THEN 'no' ELSE 'yes' END AS HasPartition
FROM sys.tables AS t
LEFT JOIN sys.objects AS o ON t.object_id = o.object_id
LEFT JOIN sys.schemas AS s ON o.schema_id = s.schema_id
LEFT JOIN sys.indexes AS i ON t.object_id = i.object_id
LEFT JOIN sys.index_columns AS ic ON ic.partition_ordinal > 0 AND ic.index_id = i.index_id AND ic.object_id = t.object_id
LEFT JOIN sys.columns AS c ON c.object_id = ic.object_id AND c.column_id = ic.column_id
LEFT JOIN sys.types AS y ON c.system_type_id = y.system_type_id
WHERE s.name='[your schema]' AND t.name = '[your table name]'

Se la tabella ha una partizione fisica, viene visualizzato "HasPartition" come "sì".

Usare l'istruzione COPY per caricare i dati in Azure Synapse Analytics

L'uso dell'istruzione COPY è un modo semplice e flessibile per caricare i dati in Azure Synapse Analytics con velocità effettiva elevata. Per altre informazioni, controllare caricamento bulk dei dati usando l'istruzione COPY

• Se i dati di origine si trovano in BLOB di Azure o Azure Data Lake Storage Gen2e il formato è compatibile con l'istruzione COPY, è possibile usare l'attività di copia per richiamare direttamente l'istruzione COPY per consentire ad Azure Synapse Analytics di estrarre i dati dall'origine. Per maggiori dettagli, vedere Copia diretta usando l’istruzione COPY.
• Se l'archivio dati di origine e il formato non sono originariamente supportati dall'istruzione COPY, usare invece la copia di staging usando la funzionalità istruzione COPY. La funzionalità copia di staging assicura inoltre una migliore velocità effettiva, Converte automaticamente i dati in un formato compatibile con l'istruzione COPY, archivia i dati nell'archivio BLOB di Azure e quindi chiama l'istruzione COPY per caricare i dati in Azure Synapse Analytics.

Copia diretta tramite l'istruzione COPY

L'istruzione COPY di Azure Synapse Analytics supporta direttamente BLOB di Azure e Azure Data Lake Storage Gen2. Se i dati di origine soddisfano i criteri descritti in questa sezione, usare l’istruzione COPY per copiare direttamente dall'archivio dati di origine ad Azure Synapse Analytics. In caso contrario, usare Copia di staging usando l'istruzione COPY. Il servizio controlla le impostazioni e, se i criteri non vengono soddisfatti, l'esecuzione dell'attività di copia non riesce.

1. Il servizio collegato all'origine e il formato hanno i tipi e i metodi di autenticazione seguenti:

   Tipo di archivio dati di origine supportato	Formato supportato	Tipo di autenticazione di origine supportato
   BLOB di Azure	Testo delimitato	Autenticazione della chiave dell'account, autenticazione della firma di accesso condiviso, autenticazione dell'entità servizio (tramite ServicePrincipalKey), autenticazione dell'identità gestita assegnata dal sistema
   	Parquet	Autenticazione della chiave dell'account, autenticazione con firma di accesso condiviso
   	ORC	Autenticazione della chiave dell'account, autenticazione con firma di accesso condiviso
   Azure Data Lake Storage Gen2	Testo delimitato Parquet ORC	Autenticazione della chiave dell'account, autenticazione dell'entità servizio (tramite ServicePrincipalKey), autenticazione della firma di accesso condiviso, autenticazione dell'identità gestita assegnata dal sistema

   Importante

   • Quando si usa l'autenticazione dell'identità gestita per il servizio collegato di archiviazione, apprendere le configurazioni necessarie rispettivamente per BLOB di Azure e Azure Data Lake Storage Gen2.
   • Se l'archiviazione di Azure è configurata con l'endpoint del servizio di rete virtuale, è necessario usare l'autenticazione dell'identità gestita con "consenti il servizio Microsoft attendibile" abilitato nell'account di archiviazione, vedere Impatto sull'uso degli endpoint del servizio di rete virtuale con Archiviazione di Azure.

2. Le impostazioni del formato sono le seguenti:

   1. Per Parquet: compression può essere no compression, Snappy o GZip.
   2. Per ORC: compression può essere no compression, zlib o Snappy.
   3. Per Testo delimitato:
      1. rowDelimiter è impostato in modo esplicito come single character o "\r\n", il valore predefinito non è supportato.
      2. nullValue è impostato sul valore predefinito o su empty string ("").
      3. encodingName è impostato sul valore predefinito o su utf-8 o utf-16.
      4. escapeChar deve essere uguale a quoteChar e non è vuoto.
      5. skipLineCount è impostato sul valore predefinito o su 0.
      6. compression può essere no compression o GZip.

3. Se l'origine è una cartella, recursive nell'attività di copia deve essere impostato su true e wildcardFilename deve essere * o *.*.

4. wildcardFolderPath , wildcardFilename (diverso da * o *.*), modifiedDateTimeStart, modifiedDateTimeEnd, prefix, enablePartitionDiscovery and additionalColumns non sono specificati.

Le impostazioni dell'istruzione COPY seguenti sono supportate in allowCopyCommand nell'attività di copia:

Proprietà	Descrizione	Richiesto
defaultValues	Specifica i valori predefiniti per ogni colonna di destinazione in Azure Synapse Analytics. I valori predefiniti nella proprietà sovrascrivono il vincolo DEFAULT impostato nel data warehouse e la colonna Identity non può avere un valore predefinito.	No
additionalOptions	Opzioni aggiuntive che verranno passate a un'istruzione COPY di Azure Synapse Analytics direttamente nella clausola "With" in istruzione COPY. Racchiudere il valore tra virgolette come previsto dai requisiti dell'istruzione COPY.	No

"activities":[
    {
        "name": "CopyFromAzureBlobToSQLDataWarehouseViaCOPY",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "ParquetDataset",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "AzureSQLDWDataset",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "ParquetSource",
                "storeSettings":{
                    "type": "AzureBlobStorageReadSettings",
                    "recursive": true
                }
            },
            "sink": {
                "type": "SqlDWSink",
                "allowCopyCommand": true,
                "copyCommandSettings": {
                    "defaultValues": [
                        {
                            "columnName": "col_string",
                            "defaultValue": "DefaultStringValue"
                        }
                    ],
                    "additionalOptions": {
                        "MAXERRORS": "10000",
                        "DATEFORMAT": "'ymd'"
                    }
                }
            },
            "enableSkipIncompatibleRow": true
        }
    }
]

Copia di staging tramite l'istruzione COPY

Quando i dati di origine non sono compatibili in modo nativo con l'istruzione COPY, abilitare la copia dei dati tramite un BLOB di Azure di staging provvisorio o Azure Data Lake Storage Gen2 (non può essere Archiviazione Premium di Azure). In questo caso, il servizio converte automaticamente i dati in modo da soddisfare i requisiti di formato dei dati dell'istruzione COPY. Richiama quindi l'istruzione COPY per caricare i dati in Azure Synapse Analytics. Infine, pulisce i dati temporanei dall'archiviazione. Per informazioni dettagliate sulla copia dei dati tramite una gestione temporanea, vedere Copia di staging.

Per usare questa funzionalità, creare un servizio collegato di Archiviazione BLOB di Azure o un servizio collegato Azure Data Lake Storage Gen2 con chiave dell'account o l'autenticazione dell'identità gestita dal sistema che fa riferimento all'account di archiviazione di Azure come risorsa di archiviazione temporanea.

"activities":[
    {
        "name": "CopyFromSQLServerToSQLDataWarehouseViaCOPYstatement",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "SQLServerDataset",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "AzureSQLDWDataset",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "SqlSource",
            },
            "sink": {
                "type": "SqlDWSink",
                "allowCopyCommand": true
            },
            "stagingSettings": {
                "linkedServiceName": {
                    "referenceName": "MyStagingStorage",
                    "type": "LinkedServiceReference"
                }
            }
        }
    }
]

Usare PolyBase per caricare dati in Azure Synapse Analytics

PolyBase consente di caricare in modo efficiente grandi quantità di dati in Azure Synapse Analytics con una velocità effettiva elevata. L'uso di PolyBase consente un miglioramento significativo della velocità effettiva rispetto al meccanismo BULKINSERT predefinito.

• Se l'origine dati è in Archiviazione BLOB di Azure o Azure Data Lake Storage Gen2 e il formato è compatibile con PolyBase, è possibile usare l'attività di copia per richiamare direttamente PolyBase e consentire ad Azure Synapse Analytics di estrarre i dati dall'origine. Per maggiori dettagli, vedere Copia diretta tramite 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. La funzionalità copia di staging assicura inoltre una migliore velocità effettiva, convertendo automaticamente i dati in un formato compatibile con PolyBase, archiviando i dati nell'archiviazione BLOB di Azure e infine chiamando PolyBase per caricare i dati in Azure Synapse Analytics.

Le impostazioni di PolyBase seguenti sono supportate in polyBaseSettings nell'attività di copia:

Proprietà	Descrizione	Richiesto
rejectValue	Specifica il numero o la percentuale di righe che è possibile rifiutare prima che la query abbia esito negativo. Per altre informazioni sulle opzioni di rifiuto di PolyBase, vedere la sezione Argomenti in CREATE EXTERNAL TABLE (Transact-SQL). I valori consentiti sono 0 (predefinito), 1, 2 e così via.	No
rejectType	Indica se l'opzione rejectValue viene specificata come valore letterale o come percentuale. I valori consentiti sono Value (predefinito) e Percentage.	No
rejectSampleValue	Determina il numero di righe da recuperare prima che PolyBase ricalcoli la percentuale di righe rifiutate. I valori consentiti sono 1, 2 e così via.	Sì se rejectType è percentage.
useTypeDefault	Specifica come gestire valori mancanti nei file di testo delimitato quando PolyBase recupera i dati dal file di testo. Per altre informazioni su questa proprietà, vedere la sezione Arguments (Argomenti) in CREATE EXTERNAL FILE FORMAT (Transact-SQL). I valori consentiti sono True e False (predefinito).	No

Copia diretta tramite PolyBase

PolyBase di Azure Synapse Analytics supporta direttamente BLOB di Azure e Azure Data Lake Storage Gen2. Se i dati di origine soddisfano i criteri descritti in questa sezione, usare PolyBase per copiare direttamente dall'archivio dati di origine ad Azure Synapse Analytics. In caso contrario, usare la copia di staging tramite PolyBase.

Se i requisiti non sono soddisfatti, il servizio controlla le impostazioni e esegue automaticamente il fallback al meccanismo BULKINSERT per lo spostamento dei dati.

1. Il servizio collegato all'origine ha i tipi e i metodi di autenticazione seguenti:

   Tipo di archivio dati di origine supportato	Tipo di autenticazione di origine supportato
   BLOB di Azure	Autenticazione della chiave dell'account, autenticazione dell'identità gestita assegnata dal sistema
   Azure Data Lake Storage Gen2	Autenticazione della chiave dell'account, autenticazione dell'identità gestita assegnata dal sistema

   Importante

   • Quando si usa l'autenticazione dell'identità gestita per il servizio collegato di archiviazione, apprendere le configurazioni necessarie rispettivamente per BLOB di Azure e Azure Data Lake Storage Gen2.
   • Se l'archiviazione di Azure è configurata con l'endpoint del servizio di rete virtuale, è necessario usare l'autenticazione dell'identità gestita con "consenti il servizio Microsoft attendibile" abilitato nell'account di archiviazione, vedere Impatto sull'uso degli endpoint del servizio di rete virtuale con Archiviazione di Azure.

2. Il formato dei dati di origine è Parquet, ORC o Testo delimitato, con le configurazioni seguenti:

   1. Il percorso della cartella non contiene il filtro con caratteri jolly.
   2. Il nome file è vuoto o punta a un singolo file. Se si specifica il nome file con caratteri jolly nell'attività di copia, può essere solo * o *.*.
   3. rowDelimiter è impostazione predefinita, \n, \r\n o \r.
   4. nullValue è impostato sul valore predefinito o su una stringa vuota ("") e treatEmptyAsNull è impostato sul valore predefinito o su true.
   5. encodingName è impostato sul valore predefinito o su utf-8.
   6. quoteChar, escapeChar e skipLineCount non sono specificati. Il supporto di PolyBase ignora la riga di intestazione che può essere configurata come firstRowAsHeader.
   7. compression può essere no compression, GZip o Deflate.

3. Se l'origine è una cartella, recursive nell'attività di copia deve essere impostato su true.

4. wildcardFolderPath, wildcardFilename, modifiedDateTimeStart, modifiedDateTimeEnd e prefix, enablePartitionDiscovery, e additionalColumns non sono specificati.

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

Copia di staging tramite PolyBase

Quando i dati di origine non sono compatibili in modo nativo con PolyBase, abilitare la copia dei dati tramite un BLOB di Azure di staging provvisorio o Azure Data Lake Storage Gen2 (non può essere Archiviazione Premium di Azure). In questo caso, il servizio converte automaticamente i dati in modo da soddisfare i requisiti di formato dei dati di PolyBase. Richiama quindi PolyBase per caricare i dati in Azure Synapse Analytics. Infine, pulisce i dati temporanei dall'archiviazione. Per informazioni dettagliate sulla copia dei dati tramite una gestione temporanea, vedere Copia di staging.

Per usare questa funzionalità, creare un servizio collegato di Archiviazione BLOB di Azure o un servizio collegato Azure Data Lake Storage Gen2 con chiave dell'account o l'autenticazione dell'identità gestita che fa riferimento all'account di archiviazione di Azure come risorsa di archiviazione temporanea.

"activities":[
    {
        "name": "CopyFromSQLServerToSQLDataWarehouseViaPolyBase",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "SQLServerDataset",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "AzureSQLDWDataset",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "SqlSource",
            },
            "sink": {
                "type": "SqlDWSink",
                "allowPolyBase": true
            },
            "enableStaging": true,
            "stagingSettings": {
                "linkedServiceName": {
                    "referenceName": "MyStagingStorage",
                    "type": "LinkedServiceReference"
                }
            }
        }
    }
]

Procedure consigliate per l'uso di PolyBase

Le sezioni seguenti illustrano le procedure consigliate in aggiunta alle procedure descritte in Procedure consigliate per Azure Synapse Analytics.

Autorizzazione database obbligatoria

Per usare PolyBase, l'utente che carica i dati in Azure Synapse Analytics deve avere autorizzazione "CONTROL" nel database di destinazione. Un modo per ottenere questo risultato consiste nell'aggiungere l'utente come membro del ruolo db_owner. Informazioni su come eseguire questa operazione nella panoramica di Azure Synapse Analytics.

Limitazioni alle dimensioni delle righe e al tipo di dati

Le operazioni di caricamento di PolyBase sono limitate alle righe inferiori a 1 MB, e non è possibile usare PolyBase per caricare dati in VARCHR(MAX), NVARCHAR(MAX), or VARBINARY(MAX). Per altre informazioni, vedere Limiti di capacità del servizio Azure Synapse Analytics.

Quando i dati di origine hanno righe di dimensioni superiori a 1 MB, è consigliabile suddividere verticalmente le tabelle di origine in tabelle più piccole. Assicurarsi che le dimensioni massime di ogni riga non superino il limite previsto. Le tabelle più piccole possono essere quindi caricate usando PolyBase e unite in Azure Synapse Analytics.

In alternativa, per i dati con colonne di grandi dimensioni, è possibile usare un'opzione diversa da PolyBase per caricare i dati disattivando l'impostazione "Allow PolyBase" (Consenti PolyBase).

Classe di risorse di Azure Synapse Analytics

Per ottenere la migliore velocità effettiva possibile, assegnare una classe di risorse più ampia all'utente che carica i dati in Azure Synapse Analytics tramite PolyBase.

Risoluzione dei problemi di PolyBase

Caricamento nella colonna Decimal

Se i dati di origine sono in formato testo o in altri archivi non compatibili con PolyBase (con copia di staging e PolyBase) e contengono un valore vuoto da caricare nella colonna Decimal di Azure Synapse Analytics, è possibile che venga visualizzato l'errore seguente:

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

La soluzione consiste nel deselezionare l'opzione "Use type default" (Tipo di uso predefinito) (false) nel sink dell'attività di copia -> PolyBase Settings (Impostazioni PolyBase). "USE_TYPE_DEFAULT" è una configurazione nativa di PolyBase che specifica come gestire valori mancanti nei file di testo delimitato quando PolyBase recupera i dati dal file di testo.

Controllare la proprietà tableName in Azure Synapse Analytics

La tabella seguente fornisce alcuni esempi di come specificare la proprietà tableName nel set di dati JSON, mostrando diverse combinazioni di nomi di schema e di tabella.

Schema di database	Nome tabella	Proprietà JSON tableName
dbo	MyTable	MyTable o dbo.MyTable o [dbo].[MyTable]
dbo1	MyTable	dbo1.MyTable o [dbo1].[MyTable]
dbo	My.Table	[My.Table] o [dbo].[My.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. Per informazioni sul modo corretto di specificare i valori per la proprietà JSON tableName, vedere la tabella precedente.

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

Colonne con valori predefiniti

Attualmente, la funzionalità PolyBase accetta solo lo stesso numero di colonne disponibili nella tabella di destinazione. Nel caso di una tabella con quattro colonne di cui una definita con un valore predefinito, ad esempio, i dati di input devono comunque contenere quattro colonne. Un set di dati di input con tre colonne restituisce un errore simile al messaggio seguente:

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

Il valore NULL è una forma speciale di valore predefinito. Se la colonna ammette valori Null, i dati di input nel BLOB per tale colonna possono essere vuoti, ma non possono essere mancanti dal set di dati di input. PolyBase inserisce NULL per i valori mancanti in Azure Synapse Analytics.

Accesso ai file esterni non riuscito

Se viene visualizzato l'errore seguente, assicurarsi di usare l'autenticazione dell'identità gestita e di aver concesso autorizzazioni di lettura dei dati dei BLOB di archiviazione all'identità gestita dell'area di lavoro di Azure Synapse.

Job failed due to reason: at Sink '[SinkName]': shaded.msdataflow.com.microsoft.sqlserver.jdbc.SQLServerException: External file access failed due to internal error: 'Error occurred while accessing HDFS: Java exception raised on call to HdfsBridge_IsDirExist. Java exception message:\r\nHdfsBridge::isDirExist 

Per altre informazioni, vedere Concedere le autorizzazioni all'identità gestita dopo la creazione dell'area di lavoro.

Proprietà del flusso di dati per mapping

Durante la trasformazione dei dati in un flusso di dati per mapping è possibile leggere e scrivere in tabelle di Azure Synapse Analytics. Per altre informazioni, vedere la trasformazione origine e la trasformazione sink nei flussi di dati per mapping.

Trasformazione origine

Le impostazioni specifiche di Azure Synapse Analytics sono disponibili nella scheda Source Options (Opzioni origine) della trasformazione origine.

Input Specificare se l'origine deve puntare a una tabella (equivalente di Select * from <table-name>) oppure immettere una query SQL personalizzata.

Abilitare la gestione temporanea È consigliabile usare questa opzione nei carichi di lavoro di produzione con le origini di Azure Synapse Analytics. Quando si esegue un'attività del flusso di dati con le origini di Azure Synapse Analytics da una pipeline, verrà richiesto di specificare un account di archiviazione della posizione di gestione temporanea e lo userà per il caricamento di dati a fasi. È il meccanismo più rapido per caricare i dati da Azure Synapse Analytics.

• Quando si usa l'autenticazione dell'identità gestita per il servizio collegato di archiviazione, apprendere le configurazioni necessarie rispettivamente per BLOB di Azure e Azure Data Lake Storage Gen2.
• Se l'archiviazione di Azure è configurata con l'endpoint del servizio di rete virtuale, è necessario usare l'autenticazione dell'identità gestita con "consenti il servizio Microsoft attendibile" abilitato nell'account di archiviazione, vedere Impatto sull'uso degli endpoint del servizio di rete virtuale con Archiviazione di Azure.
• Quando si usa Azure Synapse pool SQL serverless come origine, l'abilitazione della gestione temporanea non è supportata.

Query: se si seleziona Query nel campo di input, immettere una query SQL per l'origine. Questa impostazione esegue l'override di qualsiasi tabella scelta nel set di dati. Le clausole Order By non sono supportate, ma è possibile impostare un'istruzione SELECT FROM completa. È possibile usare anche funzioni di tabella definite dall'utente. select * from udfGetData() è un UDF in SQL che restituisce una tabella. Questa query produrrà una tabella di origine che può essere usata nel flusso di dati. L'uso di query è anche un ottimo modo per ridurre le righe per i test o le ricerche.

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

Dimensione batch: Immettere una dimensione batch per suddividere dati di grandi dimensioni in letture. Nei flussi di dati, questa impostazione verrà usata per impostare la memorizzazione nella cache a colonne Spark. Se viene lasciato vuoto, questo campo di opzione userà le impostazioni predefinite di Spark.

Livello di isolamento: il valore predefinito per le origini SQL nel flusso di dati per mapping è Read Uncommitted. È possibile cambiare il livello di isolamento in uno dei valori seguenti:

• Read Committed
• Read Uncommitted
• Repeatable Read
• Serializable
• None (ignora il livello di isolamento)

Trasformazione sink

Le impostazioni specifiche di Azure Synapse Analytics sono disponibili nella scheda Impostazioni della trasformazione sink.

Metodo update: determina le operazioni consentite nella destinazione del database. Per impostazione predefinita, sono consentiti solo gli inserimenti. Per eseguire operazioni di aggiornamento, upsert o eliminazione di righe, è necessaria una trasformazione alter-row che applichi alle righe i tag corrispondenti alle azioni. Per le operazioni di aggiornamento, upsert ed eliminazione è necessario impostare una o più colonne chiave per determinare quale riga modificare.

Azione tabella: determina se ricreare o rimuovere tutte le righe dalla tabella di destinazione prima della scrittura.

• Nessuna: non verrà eseguita alcuna azione sulla tabella.
• Ricrea: la tabella verrà eliminata e ricreata. Questa opzione è obbligatoria se si crea una nuova tabella in modo dinamico.
• Tronca: verranno rimosse tutte le righe della tabella di destinazione.

Abilitare la gestione temporanea: consente il caricamento nei pool SQL di Azure Synapse Analytics usando il comando di copia ed è consigliato per la maggior parte dei sink di Synapse. L'archiviazione di staging è configurata nell’attività Esegui flusso di dati.

• Quando si usa l'autenticazione dell'identità gestita per il servizio collegato di archiviazione, apprendere le configurazioni necessarie rispettivamente per BLOB di Azure e Azure Data Lake Storage Gen2.
• Se l'archiviazione di Azure è configurata con l'endpoint del servizio di rete virtuale, è necessario usare l'autenticazione dell'identità gestita con "consenti il servizio Microsoft attendibile" abilitato nell'account di archiviazione, vedere Impatto sull'uso degli endpoint del servizio di rete virtuale con Archiviazione di Azure.

Dimensioni batch: controlla il numero di righe scritte in ogni bucket. Dimensioni batch più grandi migliorano l'ottimizzazione della compressione e della memoria, ma rischiano di causare eccezioni di memoria insufficiente durante la memorizzazione nella cache dei dati.

Usare lo schema sink: per impostazione predefinita, verrà creata una tabella temporanea nello schema sink come staging. In alternativa, è possibile deselezionare l’opzione Usa schema sink e, in Selezionare lo schema del database utente, specificare un nome di schema in cui Data Factory creerà una tabella di staging per caricare i dati upstream e pulirli automaticamente al completamento. Assicurarsi di disporre dell'autorizzazione create table nel database e di modificare l'autorizzazione per lo schema.

Script Pre e Post SQL: immettere script SQL a più righe che verranno eseguiti prima (pre-elaborazione) e dopo (post-elaborazione) la scrittura dei dati nel database sink

Gestione delle righe con errori

Quando si scrive in Azure Synapse Analytics, alcune righe di dati potrebbero non riuscire a causa di vincoli impostati dalla destinazione. Di seguito sono riportati alcuni errori comuni:

• I dati di tipo string o binary verrebbero troncati nella tabella
• Impossibile inserire il valore NULL nella colonna
• Conversione non riuscita durante la conversione del valore nel tipo di dati

Per impostazione predefinita, un'esecuzione del flusso di dati avrà esito negativo al primo errore che riceve. È possibile scegliere Continua in caso di errore che consente il completamento del flusso di dati anche se le singole righe presentano errori. Il servizio offre diverse opzioni per gestire queste righe di errore.

Commit transazione: scegliere se i dati vengono scritti in una singola transazione o in batch. La singola transazione offrirà prestazioni migliori e nessun dato scritto sarà visibile ad altri fino al completamento della transazione. Le transazioni batch hanno prestazioni peggiori, ma possono funzionare per set di dati di grandi dimensioni.

Output dei dati rifiutati: se abilitata, è possibile restituire le righe di errore in un file CSV in Archiviazione BLOB di Azure o in un account Azure Data Lake Storage Gen2 scelto. Verranno scritte le righe di errore con tre colonne aggiuntive: l'operazione SQL, ad esempio INSERIMENTO o AGGIORNAMENTO, il codice di errore del flusso di dati e il messaggio di errore nella riga.

Segnala l'esito positivo dell'errore: se abilitato, il flusso di dati verrà contrassegnato come operazione riuscita anche se vengono trovate righe di errore.

Proprietà dell'attività Lookup

Per altre informazioni sulle proprietà, vedere Attività Lookup.

Proprietà dell'attività GetMetadata

Per altre informazioni sulle proprietà, vedere Attività GetMetadata

Mapping dei tipi di dati per Azure Synapse Analytics

Quando si copiano i dati da o in Azure Synapse Analytics, vengono usati i mapping seguenti dai tipi di dati di Azure Synapse Analytics ai tipi di dati provvisori di Azure Data Factory. Questi mapping vengono usati anche quando si copiano dati da o in Azure Synapse Analytics usando le pipeline di Synapse, poiché le pipeline implementano anche Azure Data Factory in Azure Synapse. 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.

Tipo di dati di Azure Synapse Analytics	Tipo di dati provvisorio di Data Factory
bigint	Int64
binary	Byte[]
bit	Booleano
char	String, Char[]
data	DataOra
Datetime	DataOra
datetime2	Data/Ora
Datetimeoffset	DateTimeOffset
Decimale	Decimale
FILESTREAM attribute (varbinary(max))	Byte[]
Float	Double
image	Byte[]
int	Int32
money	Decimale
nchar	String, Char[]
numeric	Decimale
nvarchar	String, Char[]
real	Singola
rowversion	Byte[]
smalldatetime	Data/Ora
smallint	Int16
smallmoney	Decimale
Ora	TimeSpan
tinyint	Byte
uniqueidentifier	GUID
varbinary	Byte[]
varchar	String, Char[]

Aggiornare la versione di Azure Synapse Analytics

Per aggiornare la versione di Azure Synapse Analytics, nella pagina Modifica servizio collegato, selezionare Consigliato in Versione e configurare il servizio collegato facendo riferimento a Proprietà del servizio collegato per la versione consigliata.

Differenze tra la versione consigliata e la versione legacy

La tabella seguente illustra le differenze tra Azure Synapse Analytics usando la versione consigliata e la versione legacy.

Versione consigliata	Versione legacy
Supportare TLS 1.3 tramite encrypt come strict.	TLS 1.3 non è supportato.

Contenuto correlato

Per un elenco degli archivi dati supportati come origini e sink dall'attività di copia, vedere Archivi dati e formati supportati.