Copiare dati da un endpoint REST tramite Azure Data FactoryCopy data from a REST 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 REST.This article outlines how to use Copy Activity in Azure Data Factory to copy data from a REST 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 REST, il connettore HTTP e il connettore Tabella Web è la seguente:The difference among this REST connector, HTTP connector and the Web table connector are:

  • Il connettore Rest supporta specificamente la copia di dati da API RESTful;REST connector specifically supports 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, operazione supportata ma meno funzionale rispetto all'uso del connettore REST.Before this REST connector becomes available, you may happen to use 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

È possibile copiare dati da un'origine REST in qualsiasi archivio dati di sink supportato.You can copy data from a REST 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.

In particolare, questo connettore REST generico supporta:Specifically, this generic REST connector supports:

  • Il recupero dei dati da un endpoint REST tramite il metodo GET o POST.Retrieving data from a REST endpoint by using the GET or POST methods.
  • Il recupero di dati tramite una di queste autenticazioni: anonima, di base, basata sulle entità servizio AAD e basata sulle identità gestite per le risorse di Azure.Retrieving data by using one of the following authentications: Anonymous, Basic, AAD service principal, and managed identities for Azure resources.
  • La paginazione nelle API REST.Pagination in the REST APIs.
  • La copia della risposta JSON REST così com'è o la relativa analisi tramite mapping dello schema.Copying the REST JSON response as-is or parse it by using schema mapping. È supportato solo il payload della risposta in JSON.Only response payload in JSON is supported.

Suggerimento

Per testare una richiesta di recupero dei dati prima di configurare il connettore REST in Data Factory, fare riferimento alla specifica dell'API per i requisiti relativi a intestazione e corpo.To test a request for data retrieval before you configure the REST 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 offrono informazioni dettagliate sulle proprietà che è possibile usare per definire entità di Data Factory specifiche del connettore REST.The following sections provide details about properties you can use to define Data Factory entities that are specific to the REST connector.

Proprietà del servizio collegatoLinked service properties

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

ProprietàProperty DescrizioneDescription ObbligatoriaRequired
typetype La proprietà Type deve essere impostata su RestService.The type property must be set to RestService. Yes
urlurl URL di base del servizio REST.The base URL of the REST service. YesYes
enableServerCertificateValidationenableServerCertificateValidation Indica se convalidare il certificato SSL lato server quando ci si connette all'endpoint.Whether to validate server-side SSL certificate when connecting to the endpoint. NoNo
(il valore predefinito è true)(the default is true)
authenticationTypeauthenticationType Tipo di autenticazione usato per connettersi al servizio REST.Type of authentication used to connect to the REST service. I valori consentiti sono Anonymous, Basic, AadServicePrincipal e ManagedServiceIdentity.Allowed values are Anonymous, Basic, AadServicePrincipal and ManagedServiceIdentity. Per altre proprietà ed esempi su ogni valore, vedere le sezioni corrispondenti di seguito.Refer to corresponding sections below on more properties and examples respectively. 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 non è specificata, questa proprietà usa il tipo Azure Integration Runtime predefinito.If not specified, this property uses the default Azure Integration Runtime. NoNo

Usare l'autenticazione di baseUse basic authentication

Impostare la proprietà authenticationType su Basic.Set the authenticationType property to Basic. 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 REST.The user name to use to access the REST 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": "RESTLinkedService",
    "properties": {
        "type": "RestService",
        "typeProperties": {
            "authenticationType": "Basic",
            "url" : "<REST endpoint>",
            "userName": "<user name>",
            "password": {
                "type": "SecureString",
                "value": "<password>"
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Usare l'autenticazione basata sull'entità servizio AADUse AAD service principal authentication

Impostare la proprietà authenticationType su AadServicePrincipal.Set the authenticationType property to AadServicePrincipal. 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
servicePrincipalIdservicePrincipalId Specificare l'ID client. dell'applicazione Azure Active Directory.Specify the Azure Active Directory application's client ID. Yes
servicePrincipalKeyservicePrincipalKey Specificare la chiave dell'applicazione Azure Active Directory.Specify the Azure Active Directory application's key. Contrassegnare questo campo come SecureString per archiviarlo in modo sicuro in Data Factory oppure fare riferimento a un segreto archiviato in Azure Key Vault.Mark this field as a SecureString to store it securely in Data Factory, or reference a secret stored in Azure Key Vault. Yes
tenanttenant Specificare le informazioni sul tenant (nome di dominio o ID tenant) in cui si trova l'applicazione.Specify the tenant information (domain name or tenant ID) under which your application resides. Recuperarle passando il cursore del mouse sull'angolo superiore destro del portale di Azure.Retrieve it by hovering the mouse in the top-right corner of the Azure portal. Yes
aadResourceIdaadResourceId Specificare la risorsa AAD per cui si sta richiedendo l'autorizzazione, ad esempio https://management.core.windows.net.Specify the AAD resource you are requesting for authorization, e.g. https://management.core.windows.net. Yes

EsempioExample

{
    "name": "RESTLinkedService",
    "properties": {
        "type": "RestService",
        "typeProperties": {
            "url": "<REST endpoint e.g. https://www.example.com/>",
            "authenticationType": "AadServicePrincipal",
            "servicePrincipalId": "<service principal id>",
            "servicePrincipalKey": {
                "value": "<service principal key>",
                "type": "SecureString"
            },
            "tenant": "<tenant info, e.g. microsoft.onmicrosoft.com>",
            "aadResourceId": "<AAD resource URL e.g. https://management.core.windows.net>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Usare le entità gestite per l'autenticazione delle risorse di AzureUse managed identities for Azure resources authentication

Impostare la proprietà authenticationType su ManagedServiceIdentity.Set the authenticationType property to ManagedServiceIdentity. 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 ObbligatoriaRequired
aadResourceIdaadResourceId Specificare la risorsa AAD per cui si sta richiedendo l'autorizzazione, ad esempio https://management.core.windows.net.Specify the AAD resource you are requesting for authorization, e.g. https://management.core.windows.net. Yes

EsempioExample

{
    "name": "RESTLinkedService",
    "properties": {
        "type": "RestService",
        "typeProperties": {
            "url": "<REST endpoint e.g. https://www.example.com/>",
            "authenticationType": "ManagedServiceIdentity",
            "aadResourceId": "<AAD resource URL e.g. https://management.core.windows.net>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Proprietà del set di datiDataset properties

Questa sezione contiene un elenco delle proprietà supportate dal set di dati REST.This section provides a list of properties that the REST dataset supports.

Per un elenco completo delle sezioni e delle proprietà disponibili per la definizione dei set di dati, vedere Set di dati e servizi collegati.For a full list of sections and properties that are available for defining datasets, see Datasets and linked services.

Per copiare dati da REST, sono supportate le proprietà seguenti:To copy data from REST, the following properties are supported:

ProprietàProperty DescrizioneDescription ObbligatoriaRequired
typetype La proprietà type del set di dati deve essere impostata su RestResource.The type property of the dataset must be set to RestResource. 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. NoNo

Se requestMethodsi imposta additionalHeaders ,epaginationRulesnel set di dati, è ancora supportata così com'è, mentre si consiglia di usare il nuovo modello nell'origine attività in futuro. requestBodyIf you were setting requestMethod, additionalHeaders, requestBody and paginationRules in dataset, it is still supported as-is, while you are suggested to use the new model in activity source going forward.

Esempio:Example:

{
    "name": "RESTDataset",
    "properties": {
        "type": "RestResource",
        "typeProperties": {
            "relativeUrl": "<relative url>"
        },
        "schema": [],
        "linkedServiceName": {
            "referenceName": "<REST linked service name>",
            "type": "LinkedServiceReference"
        }
    }
}

Proprietà dell'attività di copiaCopy Activity properties

Questa sezione contiene un elenco delle proprietà supportate dall'origine REST.This section provides a list of properties that the REST 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.

REST come origineREST as source

Nella sezione origine dell'attività di copia sono supportate le proprietà seguenti: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 RestSource.The type property of the copy activity source must be set to RestSource. Yes
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
paginationRulespaginationRules Regole di paginazione per comporre le richieste di pagina successive.The pagination rules to compose next page requests. Per informazioni dettagliate, vedere la sezione Supporto della paginazione.Refer to pagination support section on details. NoNo
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. NoNo
requestIntervalrequestInterval Periodo di attesa prima di inviare la richiesta per la pagina successiva.The time to wait before sending the request for next page. Il valore predefinito è 00:00:01The default value is 00:00:01 NoNo

Esempio 1: Uso del metodo Get con la paginazioneExample 1: Using the Get method with pagination

"activities":[
    {
        "name": "CopyFromREST",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<REST input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "RestSource",
                "additionalHeaders": {
                    "x-user-defined": "helloworld"
                },
                "paginationRules": {
                    "AbsoluteUrl": "$.paging.next"
                },
                "httpRequestTimeout": "00:01:00"
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

Esempio 2: Uso del metodo PostExample 2: Using the Post method

"activities":[
    {
        "name": "CopyFromREST",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<REST input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "RestSource",
                "requestMethod": "Post",
                "requestBody": "<body for POST REST request>",
                "httpRequestTimeout": "00:01:00"
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

Supporto della paginazionePagination support

In genere, l'API REST limita le dimensioni del payload di risposta di una singola richiesta con un numero ragionevole. mentre per restituire una grande quantità di dati, suddivide il risultato in più pagine e richiede ai chiamanti di inviare richieste consecutive per ottenere la pagina successiva del risultato.Normally, REST API limits its response payload size of a single request under a reasonable number; while to return large amount of data, it splits the result into multiple pages and requires callers to send consecutive requests to get next page of the result. In genere la richiesta di una sola pagina è dinamica ed è composta dalle informazioni restituite dalla risposta della pagina precedente.Usually, the request for one page is dynamic and composed by the information returned from the response of previous page.

Questo connettore REST generico supporta i modelli di paginazione seguenti:This generic REST connector supports the following pagination patterns:

  • URL assoluto o relativo della richiesta successiva = valore della proprietà nel corpo della risposta correnteNext request’s absolute or relative URL = property value in current response body
  • URL assoluto o relativo della richiesta successiva = valore di intestazione nelle intestazioni di risposta correntiNext request’s absolute or relative URL = header value in current response headers
  • Parametro di query della richiesta successiva = valore della proprietà nel corpo della risposta correnteNext request’s query parameter = property value in current response body
  • Parametro di query della richiesta successiva = valore dell'intestazione nelle intestazioni della risposta correnteNext request’s query parameter = header value in current response headers
  • Intestazione della richiesta successiva = valore della proprietà nel corpo della risposta correnteNext request’s header = property value in current response body
  • Intestazione della richiesta successiva = valore dell'intestazione nelle intestazioni della risposta correnteNext request’s header = header value in current response headers

Le regole di impaginazione sono definite come un dizionario nel set di dati che contiene una o più coppie chiave-valore con distinzione tra maiuscole e minuscole.Pagination rules are defined as a dictionary in dataset which contains one or more case-sensitive key-value pairs. La configurazione verrà usata per generare la richiesta a partire dalla seconda pagina.The configuration will be used to generate the request starting from the second page. Il connettore interrompe l'iterazione quando ottiene il codice di stato HTTP 204 (nessun contenuto) o qualsiasi espressione JSONPath in "paginationRules" restituisce null.The connector will stop iterating when it gets HTTP status code 204 (No Content), or any of the JSONPath expressions in "paginationRules" returns null.

Chiavi supportate nelle regole di paginazione:Supported keys in pagination rules:

ChiaveKey DESCRIZIONEDescription
AbsoluteUrlAbsoluteUrl Indica l'URL per l'invio della richiesta successiva.Indicates the URL to issue the next request. Può essere un URL assoluto o relativo.It can be either absolute URL or relative URL.
QueryParameters.parametro_query_richiesta o QueryParameters['parametro_query_richiesta']QueryParameters.request_query_parameter OR QueryParameters['request_query_parameter'] Il valore di "parametro_query_richiesta" è definito dall'utente e fa riferimento al nome di un parametro di query nell'URL della richiesta HTTP successiva."request_query_parameter" is user-defined which references one query parameter name in the next HTTP request URL.
Headers.request_header OR Headers['request_header']Headers.request_header OR Headers['request_header'] Il valore di "intestazione_richiesta" è definito dall'utente e fa riferimento a un nome di intestazione nella richiesta HTTP successiva."request_header" is user-defined which references one header name in the next HTTP request.

Valori supportati nelle regole di paginazione:Supported values in pagination rules:

ValueValue DescrizioneDescription
Headers.intestazione_risposta o Headers['intestazione_risposta']Headers.response_header OR Headers['response_header'] Il valore di "intestazione_risposta" è definito dall'utente e fa riferimento a un nome di intestazione nella risposta HTTP corrente, il cui valore verrà usato per inviare la richiesta successiva."response_header" is user-defined which references one header name in the current HTTP response, the value of which will be used to issue next request.
Espressione JSONPath che inizia con "$" (che rappresenta la radice del corpo della risposta)A JSONPath expression starting with "$" (representing the root of the response body) Il corpo della risposta deve contenere un solo oggetto JSON.The response body should contain only one JSON object. L'espressione JSONPath deve restituire un singolo valore primitivo, che verrà usato per inviare la richiesta successiva.The JSONPath expression should return a single primitive value, which will be used to issue next request.

Esempio:Example:

L'API Viso di Facebook restituisce la risposta nella struttura seguente, nel qual caso l'URL della pagina successiva è rappresentato in paging.next:Facebook Graph API returns response in the following structure, in which case next page's URL is represented in paging.next:

{
    "data": [
        {
            "created_time": "2017-12-12T14:12:20+0000",
            "name": "album1",
            "id": "1809938745705498_1809939942372045"
        },
        {
            "created_time": "2017-12-12T14:14:03+0000",
            "name": "album2",
            "id": "1809938745705498_1809941802371859"
        },
        {
            "created_time": "2017-12-12T14:14:11+0000",
            "name": "album3",
            "id": "1809938745705498_1809941879038518"
        }
    ],
    "paging": {
        "cursors": {
            "after": "MTAxNTExOTQ1MjAwNzI5NDE=",
            "before": "NDMyNzQyODI3OTQw"
        },
        "previous": "https://graph.facebook.com/me/albums?limit=25&before=NDMyNzQyODI3OTQw",
        "next": "https://graph.facebook.com/me/albums?limit=25&after=MTAxNTExOTQ1MjAwNzI5NDE="
    }
}

La configurazione dell'origine dell'attività di copia Rest paginationRules corrispondente, in particolare, è la seguente:The corresponding REST copy activity source configuration especially the paginationRules is as follows:

"typeProperties": {
    "source": {
        "type": "RestSource",
        "paginationRules": {
            "AbsoluteUrl": "$.paging.next"
        },
        ...
    },
    "sink": {
        "type": "<sink type>"
    }
}

Esportare la risposta JSON così com'èExport JSON response as-is

È possibile usare questo connettore REST per esportare la risposta JSON dell'API REST in vari archivi basati su file.You can use this REST connector to export REST API JSON response as-is to various file-based stores. Per ottenere la copia senza schema, ignorare la sezione "struttura" (chiamata anche schema) nel set di dati e il mapping dello schema nell'attività di copia.To achieve such schema-agnostic copy, skip the "structure" (also called schema) section in dataset and schema mapping in copy activity.

Mapping dello schemaSchema mapping

Per copiare dati dall'endpoint REST al sink in formato tabulare, vedere Mapping dello schema.To copy data from REST endpoint to tabular sink, refer to schema mapping.

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.