Copiare dati da un endpoint HTTP usando Azure Data Factory o Azure Synapse Analytics

Articolo
11/16/2023

SI APPLICA A: Azure Data Factory Azure Synapse Analytics

Suggerimento

Provare Data Factory in Microsoft Fabric, una soluzione di analisi completa per le aziende. Microsoft Fabric copre tutti gli elementi, dallo spostamento dei dati all'analisi scientifica dei dati, all'analisi in tempo reale, alla business intelligence e alla creazione di report. Scopri come avviare gratuitamente una nuova versione di valutazione .

Questo articolo illustra come usare l'attività di copia in Azure Data Factory e Azure Synapse per copiare dati da un endpoint HTTP. L'articolo si basa sull'attività di copia, che presenta una panoramica generale dell'attività di copia.

La differenza tra questo connettore HTTP, il connettore REST e il connettore Tabella Web è la seguente:

Il connettore REST supporta in modo specifico la copia dei dati dalle API RESTful.
Il connettore HTTP è un connettore generico per recuperare i dati da qualsiasi endpoint HTTP, ad esempio per scaricare file. Prima che il connettore REST diventi disponibile, è possibile usare il connettore HTTP per copiare dati dalle API RESTful, supportate ma meno funzionali rispetto al connettore REST.
Il connettore Tabella Web estrae il contenuto della tabella da una pagina Web HTML.

Funzionalità supportate

Questo connettore HTTP è supportato per le funzionalità seguenti:

Funzionalità supportate	IR
attività Copy (source/-)	① ②
Attività Lookup	① ②

(1) Runtime di integrazione di Azure (2) Runtime di integrazione self-hosted

Per un elenco di archivi dati supportati come origini/sink, vedere Archivi dati supportati.

È possibile usare questo Connettore HTTP per:

Recuperare dati da un endpoint HTTP/S tramite il metodo HTTP GET o POST.
Recuperare dati tramite una di queste autenticazioni: Anonima, Di base, Digest, Windows o ClientCertificate.
Copiare la risposta HTTP così com'è o analizzarla usando i formati di file e i codec di compressione supportati.

Suggerimento

Per testare una richiesta HTTP per il recupero dei dati prima di configurare il connettore HTTP, vedere le informazioni sulla specifica dell'API per i requisiti di intestazione e corpo. È possibile usare strumenti come Postman o un Web browser per la convalida.

Prerequisiti

Se l'archivio dati si trova all'interno di una rete locale, una rete virtuale di Azure o un cloud privato virtuale di Amazon, è necessario configurare un runtime di integrazione self-hosted per connettersi.

Se l'archivio dati è un servizio dati cloud gestito, è possibile usare Azure Integration Runtime. Se l'accesso è limitato agli indirizzi IP approvati nelle regole del firewall, è possibile aggiungere indirizzi IP del runtime di integrazione di Azure all'elenco elementi consentiti.

È anche possibile usare la funzionalità di runtime di integrazione della rete virtuale gestita in Azure Data Factory per accedere alla rete locale senza installare e configurare un runtime di integrazione self-hosted.

Per altre informazioni sui meccanismi di sicurezza di rete e sulle opzioni supportate da Data Factory, vedere strategie di accesso ai dati.

Introduzione

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

Creare un servizio collegato a un'origine HTTP usando l'interfaccia utente

Usare la procedura seguente per creare un servizio collegato a un'origine HTTP nell'interfaccia utente di portale di Azure.

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
Cercare HTTP e selezionare il connettore HTTP.
Configurare i dettagli del servizio, testare la connessione e creare il nuovo servizio collegato.

Dettagli di configurazione di Connessione or

Le sezioni seguenti forniscono informazioni dettagliate sulle proprietà che è possibile usare per definire entità specifiche del connettore HTTP.

Proprietà del servizio collegato

Per il servizio collegato HTTP sono supportate le proprietà seguenti:

Proprietà	Descrizione	Richiesto
Tipo	La proprietà type deve essere impostata su HttpServer.	Sì
URL	URL di base del server Web.	Sì
enableServerCertificateValidation	Specificare se abilitare la convalida del certificato TLS/SSL del server quando ci si connette a un endpoint HTTP. Se il server HTTPS usa un certificato autofirmato, impostare questa proprietà su false.	No (il valore predefinito è true)
authenticationType	Specifica il tipo di autenticazione. I valori consentiti sono Anonymous, Basic, Digest, Windows e ClientCertificate. È anche possibile configurare le intestazioni di autenticazione nella `authHeader` proprietà . Vedere le sezioni seguenti per altre proprietà e altri esempi JSON per questi tipi di autenticazione.	Sì
authHeaders	Intestazioni di richiesta HTTP aggiuntive per l'autenticazione. Ad esempio, per usare l'autenticazione con chiave API, è possibile selezionare il tipo di autenticazione "Anonimo" e specificare la chiave API nell'intestazione.	No
connectVia	Runtime di integrazione da usare per la connessione all'archivio dati. Per altre informazioni, vedere la sezione Prerequisiti. Se questa proprietà non è specificata, viene usato il tipo Azure Integration Runtime predefinito.	No

Uso dell'autenticazione Basic, Digest o Windows

Impostare la proprietà authenticationType su Basic, Digest o Windows. Oltre alle proprietà generiche descritte nella sezione precedente, specificare le proprietà seguenti:

Proprietà	Descrizione	Richiesto
userName	Nome utente da usare per accedere all'endpoint HTTP.	Sì
password	Password per l'utente (valore di userName). Contrassegnare questo campo come tipo SecureString per archiviarlo in modo sicuro. È anche possibile fare riferimento a un segreto archiviato in Azure Key Vault.	Sì

Esempio

{
    "name": "HttpLinkedService",
    "properties": {
        "type": "HttpServer",
        "typeProperties": {
            "authenticationType": "Basic",
            "url" : "<HTTP endpoint>",
            "userName": "<user name>",
            "password": {
                "type": "SecureString",
                "value": "<password>"
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Usando l'autenticazione ClientCertificate

Per usare l'autenticazione ClientCertificate, impostare la proprietà authenticationType su ClientCertificate. Oltre alle proprietà generiche descritte nella sezione precedente, specificare le proprietà seguenti:

Proprietà	Descrizione	Richiesto
embeddedCertData	Dati del certificato con codifica Base64.	Specificare embeddedCertData o certThumbprint.
certThumbprint	Identificazione personale del certificato installato nell'archivio certificati del computer per il runtime di integrazione self-hosted. Si applica solo quando nella proprietà connectVia è specificato il tipo self-hosted del runtime di integrazione.	Specificare embeddedCertData o certThumbprint.
password	Password associata al certificato. Contrassegnare questo campo come tipo SecureString per archiviarlo in modo sicuro. È anche possibile fare riferimento a un segreto archiviato in Azure Key Vault.	No

Se si usa certThumbprint per l'autenticazione e il certificato è installato nell'archivio personale del computer locale, concedere l'autorizzazione di lettura al runtime di integrazione self-hosted:

Aprire Microsoft Management Console (MMC). Aggiungere lo snap-in Certificati con Computer locale come destinazione.
Espandere Certificati>Personale e quindi selezionare Certificati.
Fare clic con il tasto destro del mouse sul certificato dall'archivio personale e quindi scegliere Tutte le attività>Gestisci chiavi private.
Nella scheda Sicurezza aggiungere l'account utente in cui è in esecuzione il servizio host di Integration Runtime (DIAHostService), con l'accesso in lettura al certificato.
Il connettore HTTP carica solo certificati attendibili. Se si usa un certificato autofirmato o non integrato rilasciato da ca, per abilitare l'attendibilità, il certificato deve essere installato anche in uno degli archivi seguenti:
- Persone attendibili
- Autorità di certificazione radice di terze parti
- Autorità di certificazione radice attendibili

Esempio 1: Uso di certThumbprint

{
    "name": "HttpLinkedService",
    "properties": {
        "type": "HttpServer",
        "typeProperties": {
            "authenticationType": "ClientCertificate",
            "url": "<HTTP endpoint>",
            "certThumbprint": "<thumbprint of certificate>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Esempio 2: Uso di embeddedCertData

{
    "name": "HttpLinkedService",
    "properties": {
        "type": "HttpServer",
        "typeProperties": {
            "authenticationType": "ClientCertificate",
            "url": "<HTTP endpoint>",
            "embeddedCertData": "<Base64-encoded cert data>",
            "password": {
                "type": "SecureString",
                "value": "password of cert"
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Uso delle intestazioni di autenticazione

Inoltre, è possibile configurare le intestazioni delle richieste per l'autenticazione insieme ai tipi di autenticazione predefiniti.

Esempio: Uso dell'autenticazione della chiave API

{
    "name": "HttpLinkedService",
    "properties": {
        "type": "HttpServer",
        "typeProperties": {
            "url": "<HTTP endpoint>",
            "authenticationType": "Anonymous",
            "authHeader": {
                "x-api-key": {
                    "type": "SecureString",
                    "value": "<API 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.

Azure Data Factory supporta i formati di file seguenti. Per impostazioni basate sui formati, fare riferimento ai singoli articoli.

Le proprietà seguenti sono supportate per HTTP location nelle impostazioni nel set di dati basato sul formato:

Proprietà	Descrizione	Richiesto
Tipo	La proprietà type in `location` nel set di dati deve essere impostata su HttpServerLocation.	Sì
relativeUrl	URL relativo della risorsa che contiene i dati. Il connettore HTTP copia i dati dall'URL combinato: `[URL specified in linked service][relative URL specified in dataset]`.	No

Nota

Le dimensioni del payload della richiesta HTTP supportate sono circa 500 KB. Se le dimensioni del payload da passare all'endpoint Web sono maggiori di 500 KB, provare a inviare in batch il payload in blocchi più piccoli.

Esempio:

{
    "name": "DelimitedTextDataset",
    "properties": {
        "type": "DelimitedText",
        "linkedServiceName": {
            "referenceName": "<HTTP linked service name>",
            "type": "LinkedServiceReference"
        },
        "schema": [ < physical schema, optional, auto retrieved during authoring > ],
        "typeProperties": {
            "location": {
                "type": "HttpServerLocation",
                "relativeUrl": "<relative url>"
            },
            "columnDelimiter": ",",
            "quoteChar": "\"",
            "firstRowAsHeader": true,
            "compressionCodec": "gzip"
        }
    }
}

Proprietà dell'attività di copia

Questa sezione presenta un elenco delle proprietà supportate dall'origine HTTP.

Per un elenco completo delle sezioni e delle proprietà disponibili per la definizione delle attività, vedere Pipeline.

HTTP come origine

Azure Data Factory supporta i formati di file seguenti. Per impostazioni basate sui formati, fare riferimento ai singoli articoli.

Le proprietà seguenti sono supportate per HTTP storeSettings nelle impostazioni nell'origine di copia basata sul formato:

Proprietà	Descrizione	Richiesto
Tipo	La proprietà type in `storeSettings` deve essere impostata su HttpRead Impostazioni.	Sì
requestMethod	Metodo HTTP. I valori consentiti sono Get (predefinito) e Post.	No
additionalHeaders	Intestazioni richiesta HTTP aggiuntive.	No
requestBody	Corpo della richiesta HTTP.	No
httpRequestTimeout	Timeout (valore di TimeSpan) durante il quale la richiesta HTTP attende una risposta. Si tratta del timeout per ottenere una risposta, non per leggere i dati della risposta. Il valore predefinito è 00:01:40.	No
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

Esempio:

"activities":[
    {
        "name": "CopyFromHTTP",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<Delimited text input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "DelimitedTextSource",
                "formatSettings":{
                    "type": "DelimitedTextReadSettings",
                    "skipLineCount": 10
                },
                "storeSettings":{
                    "type": "HttpReadSettings",
                    "requestMethod": "Post",
                    "additionalHeaders": "<header key: header value>\n<header key: header value>\n",
                    "requestBody": "<body for POST HTTP request>"
                }
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

Proprietà dell'attività Lookup

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

Modalità legacy

Nota

I modelli seguenti sono ancora supportati così come sono per la compatibilità con le versioni precedenti. Si consiglia di usare il nuovo modello menzionato nelle sezioni precedenti in futuro e l'interfaccia utente di creazione è passata alla generazione del nuovo modello.

Modello di set di dati legacy

Proprietà	Descrizione	Richiesto
Tipo	La proprietà type del set di dati deve essere impostata su HttpFile.	Sì
relativeUrl	URL relativo della risorsa che contiene i dati. Quando questa proprietà non è specificata, viene usato solo l'URL indicato nella definizione del servizio collegato.	No
requestMethod	Metodo HTTP. I valori consentiti sono Get (predefinito) e Post.	No
additionalHeaders	Intestazioni richiesta HTTP aggiuntive.	No
requestBody	Corpo della richiesta HTTP.	No
format	Se si vuole recuperare dati dall'endpoint HTTP così come sono, senza analizzarli, e quindi copiarli in un archivio basato su file, ignorare la sezione format nelle definizioni del set di dati di input e di output. Se si vuole analizzare il contenuto della risposta HTTP durante la copia, sono supportati questi tipi di formato file: TextFormat, JsonFormat, AvroFormat, OrcFormat e ParquetFormat. In format impostare la proprietà type su uno di questi valori. Per altre informazioni, vedere le sezioni relative ai formati JSON, testo, Avro, Orc e Parquet.	No
compressione	Specificare il tipo e il livello di compressione dei dati. Per altre informazioni, vedere l'articolo sui formati di file supportati e i codec di compressione. Tipi supportati: GZip, Deflate, BZip2 e ZipDeflate. Livelli supportati: Optimal e Fastest.	No

Nota

Esempio 1: Uso del metodo GET (predefinito)

{
    "name": "HttpSourceDataInput",
    "properties": {
        "type": "HttpFile",
        "linkedServiceName": {
            "referenceName": "<HTTP linked service name>",
            "type": "LinkedServiceReference"
        },
        "typeProperties": {
            "relativeUrl": "<relative url>",
            "additionalHeaders": "Connection: keep-alive\nUser-Agent: Mozilla/5.0\n"
        }
    }
}

Esempio 2: Uso del metodo POST

{
    "name": "HttpSourceDataInput",
    "properties": {
        "type": "HttpFile",
        "linkedServiceName": {
            "referenceName": "<HTTP linked service name>",
            "type": "LinkedServiceReference"
        },
        "typeProperties": {
            "relativeUrl": "<relative url>",
            "requestMethod": "Post",
            "requestBody": "<body for POST HTTP request>"
        }
    }
}

Modello di origine dell'attività di copia legacy

Proprietà	Descrizione	Richiesto
Tipo	La proprietà type dell'origine dell'attività di copia deve essere impostata su HttpSource.	Sì
httpRequestTimeout	Timeout (valore di TimeSpan) durante il quale la richiesta HTTP attende una risposta. Si tratta del timeout per ottenere una risposta, non per leggere i dati della risposta. Il valore predefinito è 00:01:40.	No

Esempio

"activities":[
    {
        "name": "CopyFromHTTP",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<HTTP input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "HttpSource",
                "httpRequestTimeout": "00:01:00"
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

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

Copiare dati da un endpoint HTTP usando Azure Data Factory o Azure Synapse Analytics

Funzionalità supportate

Prerequisiti

Introduzione

Creare un servizio collegato a un'origine HTTP usando l'interfaccia utente

Dettagli di configurazione di Connessione or

Proprietà del servizio collegato

Uso dell'autenticazione Basic, Digest o Windows

Usando l'autenticazione ClientCertificate

Uso delle intestazioni di autenticazione

Proprietà del set di dati

Proprietà dell'attività di copia

HTTP come origine

Proprietà dell'attività Lookup

Modalità legacy

Modello di set di dati legacy

Modello di origine dell'attività di copia legacy

Contenuto correlato

Risorse aggiuntive