Copiare dati da un endpoint HTTP tramite Azure Data FactoryCopy data from an HTTP endpoint by using Azure Data Factory

Questo articolo descrive come usare l'attività di copia in Azure Data Factory per copiare dati da un endpoint HTTP.This article outlines how to use Copy Activity in Azure Data Factory to copy data from an HTTP endpoint. L'articolo è basato su Attività di copia in Azure Data Factory, dove viene presentata una panoramica generale dell'attività di copia.The article builds on Copy Activity in Azure Data Factory, which presents a general overview of Copy Activity.

La differenza tra questo connettore HTTP, il connettore REST e il connettore Tabella Web è la seguente:The difference among this HTTP connector, the REST connector and the Web table connector are:

  • Il connettore REST supporta in modo specifico la copia dei dati dalle API RESTful.REST connector specifically support copying data from RESTful APIs;
  • Il connettore HTTP è un connettore generico per recuperare i dati da qualsiasi endpoint HTTP, ad esempio per scaricare file.HTTP connector is generic to retrieve data from any HTTP endpoint, e.g. to download 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.Before REST connector becomes available, you may happen to use the HTTP connector to copy data from RESTful API, which is supported but less functional comparing to REST connector.
  • Il connettore Tabella Web estrae il contenuto della tabella da una pagina Web HTML.Web table connector extracts table content from an HTML webpage.

Funzionalità supportateSupported capabilities

Questo connettore HTTP è supportato per le attività seguenti:This HTTP connector is supported for the following activities:

È possibile copiare dati da un'origine HTTP in qualsiasi archivio dati sink supportato.You can copy data from an HTTP source to any supported sink data store. Per un elenco degli archivi dati supportati dall'attività di copia come origini e sink, vedere Archivi dati e formati supportati.For a list of data stores that Copy Activity supports as sources and sinks, see Supported data stores and formats.

È possibile usare questo Connettore HTTP per:You can use this HTTP connector to:

  • Recuperare dati da un endpoint HTTP/S tramite il metodo HTTP GET o POST.Retrieve data from an HTTP/S endpoint by using the HTTP GET or POST methods.
  • Recuperare dati usando una delle autenticazioni seguenti: Anonymous, Basic, Digest, Windows o ClientCertificate.Retrieve data by using one of the following authentications: Anonymous, Basic, Digest, Windows, or ClientCertificate.
  • Copiare la risposta HTTP così com'è o analizzarla usando i formati di file e i codec di compressione supportati.Copy the HTTP response as-is or parse it by using supported file formats and compression codecs.

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.To test an HTTP request for data retrieval before you configure the HTTP connector in Data Factory, learn about the API specification for header and body requirements. È possibile usare strumenti come Postman o un Web browser per la convalida.You can use tools like Postman or a web browser to validate.

PrerequisitiPrerequisites

Se l'archivio dati è configurato in uno dei modi seguenti, è necessario configurare un Integration Runtime self-hosted per connettersi a questo archivio dati:If your data store is configured in one of the following ways, you need to set up a Self-hosted Integration Runtime in order to connect to this data store:

  • L'archivio dati si trova all'interno di una rete locale, all'interno di una rete virtuale di Azure o all'interno di un cloud privato virtuale di Amazon.The data store is located inside an on-premises network, inside Azure Virtual Network, or inside Amazon Virtual Private Cloud.
  • L'archivio dati è un servizio dati cloud gestito in cui l'accesso è limitato agli indirizzi IP consentiti nelle regole del firewall.The data store is a managed cloud data service where the access is restricted to IPs whitelisted in the firewall rules.

Attività inizialiGet started

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

Le sezioni seguenti presentano informazioni dettagliate sulle proprietà che è possibile usare per definire entità di Data Factory specifiche per il connettore HTTP.The following sections provide details about properties you can use to define Data Factory entities that are specific to the HTTP connector.

Proprietà del servizio collegatoLinked service properties

Per il servizio collegato HTTP sono supportate le proprietà seguenti:The following properties are supported for the HTTP linked service:

ProprietàProperty DescrizioneDescription ObbligatoriaRequired
typetype La proprietà type deve essere impostata su HttpServer.The type property must be set to HttpServer. Yes
urlurl URL di base del server Web.The base URL to the web server. Yes
enableServerCertificateValidationenableServerCertificateValidation Specificare se abilitare la convalida del certificato SSL del server quando ci si connette a un endpoint HTTP.Specify whether to enable server SSL certificate validation when you connect to an HTTP endpoint. Se il server HTTPS usa un certificato autofirmato, impostare questa proprietà su false.If your HTTPS server uses a self-signed certificate, set this property to false. N.No
(il valore predefinito è true)(the default is true)
authenticationTypeauthenticationType Specifica il tipo di autenticazione.Specifies the authentication type. I valori consentiti sono Anonymous, Basic, Digest, Windows e ClientCertificate.Allowed values are Anonymous, Basic, Digest, Windows, and ClientCertificate.

Vedere le sezioni seguenti per altre proprietà e altri esempi JSON per questi tipi di autenticazione.See the sections that follow this table for more properties and JSON samples for these authentication types.
Yes
connectViaconnectVia Runtime di integrazione da usare per la connessione all'archivio dati.The Integration Runtime to use to connect to the data store. Ulteriori informazioni sono disponibili nella sezione prerequisiti .Learn more from Prerequisites section. Se questa proprietà non è specificata, viene usato il tipo Azure Integration Runtime predefinito.If not specified, the default Azure Integration Runtime is used. NoNo

Usando l'autenticazione Basic, Digest o WindowsUsing Basic, Digest, or Windows authentication

Impostare la proprietà authenticationType su Basic, Digest o Windows.Set the authenticationType property to Basic, Digest, or Windows. Oltre alle proprietà generiche descritte nella sezione precedente, specificare le proprietà seguenti:In addition to the generic properties that are described in the preceding section, specify the following properties:

ProprietàProperty DescrizioneDescription ObbligatorioRequired
userNameuserName Nome utente da usare per accedere all'endpoint HTTP.The user name to use to access the HTTP endpoint. Yes
passwordpassword Password per l'utente (valore di userName).The password for the user (the userName value). Contrassegnare questo campo come tipo SecureString per archiviare la password in modo sicuro in Data Factory.Mark this field as a SecureString type to store it securely in Data Factory. È anche possibile fare riferimento a un segreto archiviato in Azure Key Vault.You can also reference a secret stored in Azure Key Vault. Yes

EsempioExample

{
    "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 ClientCertificateUsing ClientCertificate authentication

Per usare l'autenticazione ClientCertificate, impostare la proprietà authenticationType su ClientCertificate.To use ClientCertificate authentication, set the authenticationType property to ClientCertificate. Oltre alle proprietà generiche descritte nella sezione precedente, specificare le proprietà seguenti:In addition to the generic properties that are described in the preceding section, specify the following properties:

ProprietàProperty DescrizioneDescription ObbligatorioRequired
embeddedCertDataembeddedCertData Dati del certificato con codifica Base64.Base64-encoded certificate data. Specificare embeddedCertData o certThumbprint.Specify either embeddedCertData or certThumbprint.
certThumbprintcertThumbprint Identificazione personale del certificato installato nell'archivio certificati del computer per il runtime di integrazione self-hosted.The thumbprint of the certificate that's installed on your self-hosted Integration Runtime machine's cert store. Si applica solo quando nella proprietà connectVia è specificato il tipo self-hosted del runtime di integrazione.Applies only when the self-hosted type of Integration Runtime is specified in the connectVia property. Specificare embeddedCertData o certThumbprint.Specify either embeddedCertData or certThumbprint.
passwordpassword Password associata al certificato.The password that's associated with the certificate. Contrassegnare questo campo come tipo SecureString per archiviare la password in modo sicuro in Data Factory.Mark this field as a SecureString type to store it securely in Data Factory. È anche possibile fare riferimento a un segreto archiviato in Azure Key Vault.You can also reference a secret stored in Azure Key Vault. N.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:If you use certThumbprint for authentication and the certificate is installed in the personal store of the local computer, grant read permissions to the self-hosted Integration Runtime:

  1. Aprire Microsoft Management Console (MMC).Open the Microsoft Management Console (MMC). Aggiungere lo snap-in Certificati con Computer locale come destinazione.Add the Certificates snap-in that targets Local Computer.
  2. Espandere Certificati > Personale e quindi selezionare Certificati.Expand Certificates > Personal, and then select Certificates.
  3. Fare clic con il tasto destro del mouse sul certificato dall'archivio personale e quindi scegliere Tutte le attività > Gestisci chiavi private.Right-click the certificate from the personal store, and then select All Tasks > Manage Private Keys.
  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.On the Security tab, add the user account under which the Integration Runtime Host Service (DIAHostService) is running, with read access to the certificate.

Esempio 1: Uso di certThumbprintExample 1: Using 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 embeddedCertDataExample 2: Using 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"
        }
    }
}

Proprietà del set di datiDataset properties

Per un elenco completo delle sezioni e delle proprietà disponibili per la definizione dei set di dati, vedere l'articolo Set di dati.For a full list of sections and properties available for defining datasets, see the Datasets article.

Set di dati parquet, delimitato di testo, JSON, avro e Binary FormatParquet, delimited text, JSON, Avro and binary format dataset

Per copiare dati da e verso parquet, testo delimitato, JSON, avro e formato binario, vedere l'articolo formato parquet, formato testo delimitato, formato avro e formato binario nel set di dati basato su formato e impostazioni supportate .To copy data to and from Parquet, delimited text, JSON, Avro and binary format, refer to Parquet format, Delimited text format, Avro format and Binary format article on format-based dataset and supported settings. Le proprietà seguenti sono supportate per http location in impostazioni nel set di dati basato sul formato:The following properties are supported for HTTP under location settings in format-based dataset:

ProprietàProperty DescrizioneDescription ObbligatoriaRequired
typetype La proprietà location Type nel set di dati deve essere impostata su HttpServerLocation.The type property under location in dataset must be set to HttpServerLocation. Yes
relativeUrlrelativeUrl URL relativo della risorsa che contiene i dati.A relative URL to the resource that contains the data. N.No

Nota

Le dimensioni del payload della richiesta HTTP supportate sono circa 500 KB.The supported HTTP request payload size is around 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.If the payload size you want to pass to your web endpoint is larger than 500 KB, consider batching the payload in smaller chunks.

Nota

Il set di dati di tipo HttpFile con formato parquet/testo indicato nella sezione successiva è ancora supportato così com'è per l'attività di copia/ricerca per la compatibilità con le versioni precedenti.HttpFile type dataset with Parquet/Text format mentioned in next section is still supported as-is for Copy/Lookup activity for backward compatibility. Si consiglia di usare questo nuovo modello in futuro e l'interfaccia utente di creazione di ADF ha cambiato la generazione di questi nuovi tipi.You are suggested to use this new model going forward, and the ADF authoring UI has switched to generating these new types.

Esempio:Example:

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

Set di dati di altri formatiOther format dataset

Per copiare dati da HTTP in formato ORC, sono supportate le proprietà seguenti:To copy data from HTTP in ORC format, the following properties are supported:

ProprietàProperty DescrizioneDescription ObbligatoriaRequired
typetype La proprietà type del set di dati deve essere impostata su HttpFile.The type property of the dataset must be set to HttpFile. Yes
relativeUrlrelativeUrl URL relativo della risorsa che contiene i dati.A relative URL to the resource that contains the data. Quando questa proprietà non è specificata, viene usato solo l'URL indicato nella definizione del servizio collegato.When this property isn't specified, only the URL that's specified in the linked service definition is used. N.No
requestMethodrequestMethod Metodo HTTP.The HTTP method. I valori consentiti sono Get (predefinito) e Post.Allowed values are Get (default) and Post. N.No
additionalHeadersadditionalHeaders Intestazioni richiesta HTTP aggiuntive.Additional HTTP request headers. N.No
requestBodyrequestBody Corpo della richiesta HTTP.The body for the HTTP request. NoNo
formatformat 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.If you want to retrieve data from the HTTP endpoint as-is without parsing it, and then copy the data to a file-based store, skip the format section in both the input and output dataset definitions.

Se si vuole analizzare il contenuto della risposta HTTP durante la copia, sono supportati i tipi di formato file seguenti: TextFormat, JsonFormat, AvroFormat, OrcFormat e ParquetFormat.If you want to parse the HTTP response content during copy, the following file format types are supported: TextFormat, JsonFormat, AvroFormat, OrcFormat, and ParquetFormat. In format impostare la proprietà type su uno di questi valori.Under format, set the type property to one of these values. Per altre informazioni, vedere le sezioni relative ai formati JSON, testo, Avro, Orc e Parquet.For more information, see JSON format, Text format, Avro format, Orc format, and Parquet format.
N.No
compressioncompression Specificare il tipo e il livello di compressione dei dati.Specify the type and level of compression for the data. Per altre informazioni, vedere l'articolo sui formati di file supportati e i codec di compressione.For more information, see Supported file formats and compression codecs.

Tipi supportati: GZip, Deflate, BZip2 e ZipDeflate.Supported types: GZip, Deflate, BZip2, and ZipDeflate.
Livelli supportati: Optimal (Ottimale) e Fastest (Più veloce).Supported levels: Optimal and Fastest.
N.No

Nota

Le dimensioni del payload della richiesta HTTP supportate sono circa 500 KB.The supported HTTP request payload size is around 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.If the payload size you want to pass to your web endpoint is larger than 500 KB, consider batching the payload in smaller chunks.

Esempio 1: Uso del metodo Get (predefinito)Example 1: Using the Get method (default)

{
    "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 PostExample 2: Using the Post method

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

Proprietà dell'attività di copiaCopy Activity properties

Questa sezione presenta un elenco delle proprietà supportate dall'origine HTTP.This section provides a list of properties that the HTTP source supports.

Per un elenco completo delle sezioni e delle proprietà disponibili per la definizione delle attività, vedere Pipeline.For a full list of sections and properties that are available for defining activities, see Pipelines.

HTTP come origineHTTP as source

Parquet, delimitato testo, JSON, avro e origine del formato binarioParquet, delimited text, JSON, Avro and binary format source

Per copiare dati da parquet, testo delimitato, JSON, avro e formato binario, vedere l'articolo formato parquet, formato testo delimitato, formato avro e formato binario in origine dell'attività di copia basata su formato e supportato Impostazioni.To copy data from Parquet, delimited text, JSON, Avro and binary format, refer to Parquet format, Delimited text format, Avro format and Binary format article on format-based copy activity source and supported settings. Le proprietà seguenti sono supportate per http storeSettings in impostazioni in origine copia basata sul formato:The following properties are supported for HTTP under storeSettings settings in format-based copy source:

ProprietàProperty DescrizioneDescription ObbligatoriaRequired
typetype La proprietà Type in storeSettings deve essere impostata su HttpReadSetting.The type property under storeSettings must be set to HttpReadSetting. Yes
requestMethodrequestMethod Metodo HTTP.The HTTP method.
I valori consentiti sono Get (predefinito) e Post.Allowed values are Get (default) and Post.
N.No
addtionalHeadersaddtionalHeaders Intestazioni richiesta HTTP aggiuntive.Additional HTTP request headers. N.No
requestBodyrequestBody Corpo della richiesta HTTP.The body for the HTTP request. N.No
requestTimeoutrequestTimeout Timeout (valore di TimeSpan) durante il quale la richiesta HTTP attende una risposta.The timeout (the TimeSpan value) for the HTTP request to get a response. Si tratta del timeout per ottenere una risposta, non per leggere i dati della risposta.This value is the timeout to get a response, not the timeout to read response data. Il valore predefinito è 00:01:40.The default value is 00:01:40. N.No
maxConcurrentConnectionsmaxConcurrentConnections Numero di connessioni simultanee per la connessione all'archivio di archiviazione.The number of the connections to connect to storage store concurrently. Specificare solo quando si desidera limitare la connessione simultanea all'archivio dati.Specify only when you want to limit the concurrent connection to the data store. N.No

Nota

Per il formato di testo parquet/delimitato, l'origine dell'attività di copia di tipo HttpSource citata nella sezione successiva è ancora supportata così com'è per la compatibilità con le versioni precedenti.For Parquet/delimited text format, HttpSource type copy activity source mentioned in next section is still supported as-is for backward compatibility. Si consiglia di usare questo nuovo modello in futuro e l'interfaccia utente di creazione di ADF ha cambiato la generazione di questi nuovi tipi.You are suggested to use this new model going forward, and the ADF authoring UI has switched to generating these new types.

Esempio:Example:

"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": "DelimitedTextReadSetting",
                    "skipLineCount": 10
                },
                "storeSettings":{
                    "type": "HttpReadSetting",
                    "requestMethod": "Post",
                    "additionalHeaders": "<header key: header value>\n<header key: header value>\n",
                    "requestBody": "<body for POST HTTP request>"
                }
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

Altra origine del formatoOther format source

Per copiare dati da HTTP in formato ORC, nella sezione origine dell'attività di copia sono supportate le proprietà seguenti:To copy data from HTTP in ORC format, the following properties are supported in the copy activity source section:

ProprietàProperty DescrizioneDescription ObbligatoriaRequired
typetype La proprietà type dell'origine dell'attività di copia deve essere impostata su HttpSource.The type property of the copy activity source must be set to HttpSource. Yes
httpRequestTimeouthttpRequestTimeout Timeout (valore di TimeSpan) durante il quale la richiesta HTTP attende una risposta.The timeout (the TimeSpan value) for the HTTP request to get a response. Si tratta del timeout per ottenere una risposta, non per leggere i dati della risposta.This value is the timeout to get a response, not the timeout to read response data. Il valore predefinito è 00:01:40.The default value is 00:01:40. N.No

EsempioExample

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

Proprietà attività di ricercaLookup activity properties

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

Passaggi successiviNext steps

Per un elenco degli archivi dati supportati come origini o sink dall'attività di copia in Azure Data Factory, vedere Archivi dati e formati supportati.For a list of data stores that Copy Activity supports as sources and sinks in Azure Data Factory, see Supported data stores and formats.