Spostare i dati da un'origine OData usando Azure Data Factory

Questo articolo illustra come usare l'attività di copia in Azure Data Factory per spostare i dati da un'origine OData. Si basa sull'articolo relativo alle attività di spostamento dei dati, che offre una panoramica generale dello spostamento dei dati con l'attività di copia.

È possibile copiare dati da un'origine OData a qualsiasi archivio dati di sink supportato. Per un elenco degli archivi dati supportati come sink dall'attività di copia, vedere la tabella relativa agli archivi dati supportati. Data Factory supporta attualmente solo lo spostamento dei dati da un'origine OData ad altri archivi dati, non da altri archivi dati a un'origine OData.

Versioni supportate e tipi di autenticazione

Questo connettore OData supporta OData versione 3.0 e 4.0 e la copia dei dati dalle origini OData cloud e locali. Nel secondo caso, è necessario installare il gateway di gestione dati. Vedere l’articolo Spostare dati tra cloud e locale per informazioni dettagliate sui Gateway di Gestione dati.

Sono supportati i tipi di autenticazione seguenti:

  • Per accedere al feed OData cloud, è possibile usare l'autenticazione anonima, di base (nome utente e password) o l'autenticazione OAuth basata su Azure Active Directory.
  • Per accedere al feed OData locale, è possibile usare l'autenticazione anonima, di base (nome utente e password) o l'autenticazione di Windows.

Introduzione

È possibile creare una pipeline con l'attività di copia che sposta i dati da un'origine OData usando diversi strumenti/API.

Il modo più semplice per creare una pipeline è usare la Copia guidata. Vedere Esercitazione: Creare una pipeline usando la Copia guidata per la procedura dettagliata sulla creazione di una pipeline attenendosi alla procedura guidata per copiare i dati.

È possibile anche usare gli strumenti seguenti per creare una pipeline: portale di Azure, Visual Studio, Azure PowerShell, modello di Azure Resource Manager, API .NET e API REST. Vedere l'esercitazione sull'attività di copia per le istruzioni dettagliate sulla creazione di una pipeline con un'attività di copia.

Se si usano gli strumenti o le API, eseguire la procedura seguente per creare una pipeline che sposta i dati da un archivio dati di origine a un archivio dati sink:

  1. Creare i servizi collegati per collegare gli archivi di dati di input e output alla data factory.
  2. Creare i set di dati per rappresentare i dati di input e di output per le operazioni di copia.
  3. Creare una pipeline con un'attività di copia che accetti un set di dati come input e un set di dati come output.

Quando si usa la procedura guidata, le definizioni JSON per queste entità di data factory (servizi, set di dati e pipeline collegati) vengono create automaticamente. Quando si usano gli strumenti o le API, ad eccezione delle API .NET, usare il formato JSON per definire le entità di data factory. Per un esempio con definizioni JSON per entità di data factory utilizzate per copiare dati da un'origine OData, vedere la sezione Esempio JSON: Copiare dati da un'origine OData al BLOB di Azure di questo articolo.

Le sezioni seguenti riportano informazioni dettagliate sulle proprietà JSON che vengono usate per definire entità di data factory specifiche dell'origine OData:

Proprietà del servizio collegato

La tabella seguente contiene le descrizioni degli elementi JSON specifici del servizio collegato OData.

Proprietà Descrizione Obbligatorio
type La proprietà type deve essere impostata su: OData
URL URL del servizio OData.
authenticationType Tipo di autenticazione usato per connettersi all'origine OData.

Per OData in cloud, i valori possibili sono Anonymous, Basic e OAuth. Si noti che Azure Data Factory attualmente supporta solo OAuth basato su Azure Active Directory).

Per OData locale, i valori possibili sono Anonima, Di base e Windows.
username Specificare il nome utente se si usa l'autenticazione di base. Sì (solo se si usa l'autenticazione di base)
password Specificare la password per l'account utente specificato per il nome utente. Sì (solo se si usa l'autenticazione di base)
authorizedCredential Se si usa OAuth, fare clic sul pulsante Autorizza nella procedura guidata di copia di Data Factory o nell'Editor e immettere le credenziali. Il valore di questa proprietà viene quindi generato automaticamente. Sì (solo se si usa l'autenticazione OAuth)
gatewayName Nome del gateway che il servizio Data Factory deve usare per connettersi al servizio OData locale. Specificare solo se si copiano dati da un'origine OData locale. No

Uso dell'autenticazione di base

{
    "name": "inputLinkedService",
    "properties":
    {
        "type": "OData",
            "typeProperties":
        {
            "url": "http://services.odata.org/OData/OData.svc",
            "authenticationType": "Basic",
            "username": "username",
            "password": "password"
        }
    }
}

Uso dell'autenticazione anonima

{
    "name": "ODataLinkedService",
        "properties":
    {
        "type": "OData",
        "typeProperties":
        {
            "url": "http://services.odata.org/OData/OData.svc",
            "authenticationType": "Anonymous"
        }
    }
}

Uso dell'autenticazione di Windows per accedere all'origine OData locale

{
    "name": "inputLinkedService",
    "properties":
    {
        "type": "OData",
            "typeProperties":
        {
            "url": "<endpoint of on-premises OData source e.g. Dynamics CRM>",
            "authenticationType": "Windows",
            "username": "domain\\user",
            "password": "password",
            "gatewayName": "mygateway"
        }
    }
}

Uso dell'autenticazione OAuth per accedere all'origine OData cloud

{
    "name": "inputLinkedService",
    "properties":
    {
        "type": "OData",
            "typeProperties":
        {
            "url": "<endpoint of cloud OData source e.g. https://<tenant>.crm.dynamics.com/XRMServices/2011/OrganizationData.svc>",
            "authenticationType": "OAuth",
            "authorizedCredential": "<auto generated by clicking the Authorize button on UI>"
        }
    }
}

Proprietà dei set di dati

Per un elenco completo delle sezioni e delle proprietà disponibili per la definizione di set di dati, vedere l'articolo sulla creazione di set di dati. Le sezioni come struttura, disponibilità e criteri di un set di dati JSON sono simili per tutti i tipi di set di dati, ad esempio Azure SQL, BLOB di Azure, tabelle di Azure e così via.

La sezione typeProperties è diversa per ogni tipo di set di dati e contiene informazioni sulla posizione dei dati nell'archivio dati. La sezione typeProperties per il set di dati di tipo ODataResource , che include il set di dati OData, presenta le proprietà seguenti

Proprietà Descrizione Obbligatorio
path Percorso della risorsa OData No

Proprietà dell'attività di copia

Per un elenco completo delle sezioni e delle proprietà disponibili per la definizione delle attività, fare riferimento all'articolo Creazione di pipeline. Per tutti i tipi di attività sono disponibili proprietà come nome, descrizione, tabelle di input e output e criteri.

Le proprietà disponibili nella sezione typeProperties dell'attività variano invece in base al tipo di attività. Per l'attività di copia variano in base ai tipi di origine e sink.

Se l'origine è di tipo RelationalSource (che comprende OData), nella sezione typeProperties sono disponibili le proprietà seguenti:

Proprietà Descrizione Esempio Obbligatorio
query Usare la query personalizzata per leggere i dati. "?$select=Name, Description&$top=5" No

Mapping dei tipi per OData

Come accennato nell'articolo sulle attività di spostamento dei dati , l'attività di copia esegue conversioni di tipo automatiche dai tipi di origine ai tipi di sink con l'approccio in due passaggi seguente:

  1. Conversione dai tipi di origine nativi al tipo .NET
  2. Conversione dal tipo .NET al tipo di sink nativo

Quando si spostano dati da OData, vengono usati i mapping seguenti tra i tipi OData e i tipi .NET.

Tipo di dati OData Tipo .NET
Edm.Binary Byte[]
Edm.Boolean Booleano
Edm.Byte Byte[]
Edm.DateTime DateTime
Edm.Decimal Decimale
Edm.Double Double
Edm.Single Single
Edm.Guid Guid
Edm.Int16 Int16
Edm.Int32 Int32
Edm.Int64 Int64
Edm.SByte Int16
Edm.String String
Edm.Time Intervallo di tempo
Edm.DateTimeOffset Datetimeoffset
Nota

Tipi di dati OData complessi. Gli oggetti, ad esempio, non sono supportati.

Esempio JSON: Copiare dati da un'origine OData al BLOB di Azure

Questo esempio fornisce le definizioni JSON di esempio da usare per creare una pipeline con il Portale di Azure, Visual Studio o Azure PowerShell. Illustrano come copiare dati da un'origine OData in un archivio BLOB di Azure. Tuttavia, i dati possono essere copiati in qualsiasi sink dichiarato qui usando l'attività di copia in Azure Data Factory. L'esempio include le entità della data factory seguenti:

  1. Un servizio collegato di tipo OData.
  2. Un servizio collegato di tipo AzureStorage.
  3. Un set di dati di input di tipo ODataResource.
  4. Un set di dati di output di tipo AzureBlob.
  5. Una pipeline con attività di copia che usa RelationalSource e BlobSink.

L'esempio copia i dati dall'esecuzione di query su un'origine OData a un BLOB di Azure ogni ora. Le proprietà JSON usate in questi esempi sono descritte nelle sezioni riportate dopo gli esempi.

Servizio collegato OData: questo esempio usa l'autenticazione anonima. Per i diversi tipi di autenticazione disponibili, vedere la sezione Servizio collegato OData .

{
    "name": "ODataLinkedService",
        "properties":
    {
        "type": "OData",
            "typeProperties":
        {
            "url": "http://services.odata.org/OData/OData.svc",
            "authenticationType": "Anonymous"
            }
        }
}

Servizio collegato Archiviazione di Azure:

{
        "name": "AzureStorageLinkedService",
    "properties": {
        "type": "AzureStorage",
        "typeProperties": {
            "connectionString": "DefaultEndpointsProtocol=https;AccountName=<accountname>;AccountKey=<accountkey>"
        }
        }
}

Set di dati di input OData:

Impostando "external" su "true" si comunica al servizio Data Factory che il set di dati è esterno alla data factory e non è prodotto da un'attività al suo interno.

{
    "name": "ODataDataset",
    "properties":
    {
        "type": "ODataResource",
        "typeProperties":
        {
                "path": "Products"
        },
        "linkedServiceName": "ODataLinkedService",
        "structure": [],
        "availability": {
            "frequency": "Hour",
            "interval": 1
        },
        "external": true,
        "policy": {
            "retryInterval": "00:01:00",
            "retryTimeout": "00:10:00",
            "maximumRetry": 3                
        }
    }
}

La specifica di path nella definizione del set di dati è facoltativa.

Set di dati di output del BLOB di Azure:

I dati vengono scritti in un nuovo BLOB ogni ora (frequenza: ora, intervallo: 1). Il percorso della cartella per il BLOB viene valutato dinamicamente in base all'ora di inizio della sezione in fase di elaborazione. Il percorso della cartella usa le parti anno, mese, giorno e ora dell'ora di inizio.

{
    "name": "AzureBlobODataDataSet",
    "properties": {
        "type": "AzureBlob",
        "linkedServiceName": "AzureStorageLinkedService",
        "typeProperties": {
            "folderPath": "mycontainer/odata/yearno={Year}/monthno={Month}/dayno={Day}/hourno={Hour}",
            "format": {
                "type": "TextFormat",
                "rowDelimiter": "\n",
                "columnDelimiter": "\t"
            },
            "partitionedBy": [
                {
                    "name": "Year",
                    "value": {
                        "type": "DateTime",
                        "date": "SliceStart",
                        "format": "yyyy"
                    }
                },
                {
                    "name": "Month",
                    "value": {
                        "type": "DateTime",
                        "date": "SliceStart",
                        "format": "MM"
                    }
                },
                {
                    "name": "Day",
                    "value": {
                        "type": "DateTime",
                        "date": "SliceStart",
                        "format": "dd"
                    }
                },
                {
                    "name": "Hour",
                    "value": {
                        "type": "DateTime",
                        "date": "SliceStart",
                        "format": "HH"
                    }
                }
            ]
        },
        "availability": {
            "frequency": "Hour",
            "interval": 1
        }
    }
}

Attività di copia in una pipeline con un'origine OData e un sink BLOB:

La pipeline contiene un'attività di copia configurata per usare i set di dati di input e output ed è programmata per essere eseguita ogni ora. Nella definizione JSON della pipeline, il tipo di origine è impostato su RelationalSource e il tipo di sink è impostato su BlobSink. La query SQL specificata per la proprietà query seleziona i dati più recenti dall'origine OData.

{
    "name": "CopyODataToBlob",
    "properties": {
        "description": "pipeline for copy activity",
        "activities": [
            {
                "type": "Copy",
                "typeProperties": {
                    "source": {
                        "type": "RelationalSource",
                        "query": "?$select=Name, Description&$top=5",
                    },
                    "sink": {
                        "type": "BlobSink",
                        "writeBatchSize": 0,
                        "writeBatchTimeout": "00:00:00"
                    }
                },
                "inputs": [
                    {
                        "name": "ODataDataSet"
                    }
                ],
                "outputs": [
                    {
                        "name": "AzureBlobODataDataSet"
                    }
                ],
                "policy": {
                    "timeout": "01:00:00",
                    "concurrency": 1
                },
                "scheduler": {
                    "frequency": "Hour",
                    "interval": 1
                },
                "name": "ODataToBlob"
            }
        ],
        "start": "2017-02-01T18:00:00Z",
        "end": "2017-02-03T19:00:00Z"
    }
}

La specifica di query nella definizione della pipeline è facoltativa. L' URL è che il servizio Data Factory usa per recuperare i dati è il seguente: URL specificato nel servizio collegato (obbligatorio) + percorso specificato nel set di dati (facoltativo) + query nella pipeline (facoltativa).

Mapping dei tipi per OData

Come accennato nell'articolo sulle attività di spostamento dei dati , l'attività di copia esegue conversioni automatiche da tipi di origine a tipi di sink con l'approccio seguente in 2 passaggi:

  1. Conversione dai tipi di origine nativi al tipo .NET
  2. Conversione dal tipo .NET al tipo di sink nativo

Quando i dati vengono spostati da archivi OData, i tipi di dati OData vengono mappati ai tipi .NET.

Eseguire il mapping delle colonne dell'origine alle colonne del sink

Per informazioni sul mapping delle colonne del set di dati di origine alle colonne del set di dati del sink, vedere Mapping delle colonne del set di dati in Azure Data Factory.

Lettura ripetibile da origini relazionali

Quando si copiano dati da archivi dati relazionali, è necessario tenere presente la ripetibilità per evitare risultati imprevisti. In Azure Data Factory è possibile rieseguire una sezione manualmente. È anche possibile configurare i criteri di ripetizione per un set di dati in modo da rieseguire una sezione in caso di errore. Quando una sezione viene rieseguita in uno dei due modi, è necessario assicurarsi che non vengano letti gli stessi dati, indipendentemente da quante volte viene eseguita la sezione. Vedere Lettura ripetibile da origini relazionali.

Ottimizzazione delle prestazioni

Per informazioni sui fattori chiave che influiscono sulle prestazioni dello spostamento dei dati, ovvero dell'attività di copia, in Azure Data Factory e sui vari modi per ottimizzare tali prestazioni, vedere la Guida alle prestazioni delle attività di copia e all'ottimizzazione.