Copiare e trasformare i dati in Microsoft Fabric Warehouse usando Azure Data Factory o Azure Synapse Analytics

SI APPLICA A: Azure Data Factory Azure Synapse Analytics

Questo articolo illustra come usare l'attività Copy per copiare dati da e in Microsoft Fabric Warehouse. Per altre informazioni, leggere l'articolo introduttivo per Azure Data Factory o Azure Synapse Analytics.

Funzionalità supportate

Questo connettore Microsoft Fabric Warehouse è supportato per le funzionalità seguenti:

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

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 Microsoft Fabric Warehouse usando l'interfaccia utente

Usare la procedura seguente per creare un servizio collegato Microsoft Fabric Warehouse 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 selezionare Nuovo:

   • Azure Data Factory
   • Azure Synapse

   

2. Cercare Warehouse e selezionare il connettore.

   

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à usate per definire entità di Data Factory specifiche di Microsoft Fabric Warehouse.

Proprietà del servizio collegato

Il connettore Microsoft Fabric Warehouse supporta i tipi di autenticazione seguenti. Per informazioni dettagliate, vedere le sezioni corrispondenti:

• Autenticazione di un'entità servizio

Autenticazione dell'entità servizio

Per usare l'autenticazione basata sull'entità servizio, eseguire queste operazioni.

1. Registrare un'applicazione con Microsoft Identity Platform e aggiungere un segreto client. Successivamente, prendere nota di questi valori che si usano per definire il servizio collegato:

   • ID applicazione (client), ovvero l'ID entità servizio nel servizio collegato.
   • Valore del segreto client, ovvero la chiave dell'entità servizio nel servizio collegato.
   • ID tenant

2. Concedere all'entità servizio almeno il ruolo Collaboratore nell'area di lavoro di Microsoft Fabric. Seguire questa procedura:

   1. Andare all'area di lavoro di Microsoft Fabric, selezionare Gestisci accesso nella barra superiore. Successivamente, selezionare Aggiungi persone o gruppi.

      

      

   2. Nel riquadro Aggiungi persone immettere il nome dell'entità servizio e selezionare l'entità servizio dall'elenco a discesa.

   3. Specificare il ruolo Collaboratore o superiore (Amministratore, Membro), quindi selezionare Aggiungi.

      

   4. L'entità servizio viene visualizzata nel riquadro Gestisci accesso.

Queste sono le proprietà supportate dal servizio collegato:

Esempio: usare l'autenticazione con chiave dell'entità servizio

È anche possibile archiviare la chiave dell'entità servizio in Azure Key Vault.

{
    "name": "MicrosoftFabricWarehouseLinkedService",
    "properties": {
        "type": "Warehouse",
        "typeProperties": {
            "endpoint": "<Microsoft Fabric Warehouse server endpoint>",
            "workspaceId": "<Microsoft Fabric workspace ID>",
            "artifactId": "<Microsoft Fabric Warehouse object ID>",
            "tenant": "<tenant info, e.g. microsoft.onmicrosoft.com>",
            "servicePrincipalId": "<service principal id>",
            "servicePrincipalCredentialType": "ServicePrincipalKey",
            "servicePrincipalCredential": {
                "type": "SecureString",
                "value": "<service principal key>"
            }   
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

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 il set di dati Microsoft Fabric Warehouse sono supportate le proprietà seguenti:

Esempio di proprietà dei set di dati

{
    "name": "FabricWarehouseTableDataset",
    "properties": {
        "type": "WarehouseTable",
        "linkedServiceName": {
            "referenceName": "<Microsoft Fabric Warehouse 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 Configurazioni dell'attività di copia e Pipeline e attività. Questa sezione presenta un elenco delle proprietà supportate dall'origine e dal sink Microsoft Fabric Warehouse.

Microsoft Fabric Warehouse come origine

Per copiare dati da Microsoft Fabric Warehouse, impostare la proprietà type nell'origine dell'attività Copy su WarehouseSource. Nella sezione source dell'attività di copia sono supportate le proprietà seguenti:

Esempio: uso della query SQL

"activities":[
    {
        "name": "CopyFromMicrosoftFabricWarehouse",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<Microsoft Fabric Warehouse input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "WarehouseSource",
                "sqlReaderQuery": "SELECT * FROM MyTable"
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

Esempio: uso della stored procedure

"activities":[
    {
        "name": "CopyFromMicrosoftFabricWarehouse",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<Microsoft Fabric Warehouse input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "WarehouseSource",
                "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

Microsoft Fabric Warehouse come tipo di sink

Le pipeline di Azure Data Factory e Synapse supportano l'istruzione Usa COPY per caricare i dati in Microsoft Fabric Warehouse.

Per copiare dati in Microsoft Fabric Warehouse, impostare il tipo di sink nell'attività Copy su WarehouseSink. Nella sezione sink dell'attività di copia sono supportate le proprietà seguenti:

Esempio: sink di Microsoft Fabric Warehouse

"activities":[
    {
        "name": "CopyToMicrosoftFabricWarehouse",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<Microsoft Fabric Warehouse output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "<source type>"
            },
            "sink": {
                "type": "WarehouseSink",
                "allowCopyCommand": true,
                "tableOption": "autoCreate",
                "disableMetricsCollection": false
            }
        }
    }
]

Copia parallela da Microsoft Fabric Warehouse

Il connettore Microsoft Fabric Warehouse nell'attività Copy 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à Copy esegue query parallele sull'origine di Microsoft Fabric Warehouse per caricare i dati in base alle partizioni. Il grado di parallelismo è controllato dall'impostazione parallelCopies sull'attività di copia. Ad esempio, se si imposta parallelCopies su quattro, il servizio genera ed esegue simultaneamente quattro query in base all'opzione e alle impostazioni di partizione specificate e ogni query recupera una porzione di dati da Microsoft Fabric Warehouse.

Si consiglia di abilitare la copia parallela con il partizionamento dei dati, specialmente quando si caricano grandi quantità di dati dal database di Microsoft Fabric Warehouse. 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.

Procedure consigliate per il caricamento di dati con opzione partizione:

• Scegliere una colonna distintiva come colonna partizione (ad esempio, chiave primaria o chiave univoca) per evitare l'asimmetria dei dati.
• 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.
• “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).
• Si noti che Microsoft Fabric Warehouse può eseguire un massimo di 32 query al momento, impostando "Grado di parallelismo di copia" troppo grande può causare un problema di limitazione del warehouse.

Esempio: query con partizione a intervalli dinamici

"source": {
    "type": "WarehouseSource",
    "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>"
    }
}

Usare l'istruzione COPY per caricare i dati in Microsoft Fabric Warehouse

L'uso dell'istruzione COPY è un modo semplice e flessibile per caricare i dati in Microsoft Fabric Warehouse 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à Copy per richiamare direttamente l'istruzione COPY per consentire a Microsoft Fabric Warehouse 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 Microsoft Fabric Warehouse.

Copia diretta tramite l'istruzione COPY

L'istruzione COPY di Microsoft Fabric Warehouse supporta direttamente BLOB di Azure, Azure Data Lake Storage Gen1 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 a Microsoft Fabric Warehouse. 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.

• 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 con firma di accesso condiviso
  	Parquet	Autenticazione della chiave dell'account, autenticazione con firma di accesso condiviso
  Azure Data Lake Storage Gen2	Testo delimitato Parquet	Autenticazione della chiave dell'account, autenticazione con firma di accesso condiviso

• Le impostazioni del formato sono le seguenti:

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

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

• 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:

"activities":[
    {
        "name": "CopyFromAzureBlobToMicrosoftFabricWarehouseViaCOPY",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "ParquetDataset",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "MicrosoftFabricWarehouseDataset",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "ParquetSource",
                "storeSettings":{
                    "type": "AzureBlobStorageReadSettings",
                    "recursive": true
                }
            },
            "sink": {
                "type": "WarehouseSink",
                "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 Microsoft Fabric Warehouse. 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": "CopyFromSQLServerToMicrosoftFabricWarehouseViaCOPYstatement",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "SQLServerDataset",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "MicrosoftFabricWarehouseDataset",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "SqlSource",
            },
            "sink": {
                "type": "WarehouseSink",
                "allowCopyCommand": true
            },
            "stagingSettings": {
                "linkedServiceName": {
                    "referenceName": "MyStagingStorage",
                    "type": "LinkedServiceReference"
                }
            }
        }
    }
]

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 da/in Microsoft Fabric Warehouse. Per altre informazioni, vedere la trasformazione origine e la trasformazione sink nei flussi di dati per mapping.

Microsoft Fabric Warehouse come origine

Le impostazioni specifiche di Microsoft Fabric Warehouse sono disponibili nella scheda Opzioni origine della trasformazione origine.

Microsoft Fabric Warehouse come sink

Le impostazioni specifiche di Microsoft Fabric Warehouse sono disponibili nella scheda Impostazioni della trasformazione sink.

Gestione delle righe con errori

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 Microsoft Fabric Warehouse

Quando si copiano dati da Microsoft Fabric Warehouse, i mapping seguenti vengono usati dai tipi di dati di Microsoft Fabric Warehouse ai tipi di dati provvisori all'interno del servizio internamente. Per informazioni su come l'attività di copia esegue il mapping dello schema di origine e del tipo di dati al sink, vedere Mapping dello schema e del tipo di dati.

Passaggi successivi

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