Copiare dati da un endpoint HTTP tramite Azure Data Factory

SI APPLICA A: Azure Data Factory Azure Synapse Analytics

Questo articolo descrive come usare l'attività di copia in Azure Data Factory per copiare dati da un endpoint HTTP. L'articolo è basato su Attività di copia in Azure Data Factory, dove viene presentata 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, può capitare di usare il connettore HTTP per copiare dati dall'API RESTful, che è supportata ma meno funzionale 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 attività seguenti:

È possibile copiare dati da un'origine HTTP in qualsiasi archivio dati sink supportato. Per un elenco degli archivi dati supportati dall'attività di copia come origini e sink, vedere Archivi dati e formati 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 in Data Factory, fare riferimento alla specifica dell'API per i requisiti relativi a 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 il Azure Integration Runtime. Se l'accesso è limitato agli indirizzi IP approvati nelle regole del firewall, è possibile Azure Integration Runtime indirizzi IP consentiti.

È anche possibile usare la funzionalità runtime di integrazione della rete virtuale gestita in Azure Data Fatcory 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:

Le sezioni seguenti presentano informazioni dettagliate sulle proprietà che è possibile usare per definire entità di Data Factory specifiche per il connettore HTTP.

Proprietà del servizio collegato

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

Proprietà Descrizione Obbligatoria
type La proprietà type deve essere impostata su HttpServer.
url URL di base del server Web.
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. OAuth basato sull'utente non è supportato. È 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.
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

Usando l'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 Obbligatoria
userName Nome utente da usare per accedere all'endpoint HTTP.
password Password per l'utente (valore di userName). Contrassegnare questo campo come di tipo SecureString per l'archiviazione sicura in Data Factory. È anche possibile fare riferimento a un segreto archiviato in Azure Key Vault.

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 Obbligatoria
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 di tipo SecureString per l'archiviazione sicura in Data Factory. È 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:

  1. Aprire Microsoft Management Console (MMC). Aggiungere lo snap-in Certificati con Computer locale come destinazione.
  2. Espandere Certificati > personali e quindi selezionare Certificati.
  3. Fare clic con il pulsante destro del mouse sul certificato nell'archivio personale e quindi scegliere Tutte le attività > Gestisci chiavi private.
  4. 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.

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 con 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 nelle impostazioni nel set location di dati basato su formato:

Proprietà Descrizione Obbligatoria
type La proprietà type in location nel set di dati deve essere impostata su HttpServerLocation.
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 nelle impostazioni storeSettings nell'origine di copia basata sul formato:

Proprietà Descrizione Obbligatoria
type La proprietà type in storeSettings deve essere impostata su HttpReadSettings.
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 superiore 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. In futuro, è consigliabile usare il nuovo modello citato nelle sezioni precedenti, tenendo presente che l'interfaccia utente di creazione di Azure Data Factory è passata alla generazione del nuovo modello.

Modello di set di dati legacy

Proprietà Descrizione Obbligatoria
type La proprietà type del set di dati deve essere impostata su HttpFile.
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

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 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 Obbligatoria
type La proprietà type dell'origine dell'attività di copia deve essere impostata su HttpSource.
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>"
            }
        }
    }
]

Passaggi successivi

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