Copiare dati da Xero usando Azure Data Factory o Synapse Analytics

Articolo
10/20/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 una pipeline di Azure Data Factory o Synapse Analytics per copiare dati da Xero. Si basa sull'articolo di panoramica dell'attività di copia che presenta una panoramica generale sull'attività di copia.

Funzionalità supportate

Questo connettore Xero è 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 degli archivi dati supportati come origini/sink, vedere la tabella Archivi dati supportati.

In particolare, il connettore Xero supporta:

Autenticazione OAuth 2.0 e OAuth 1.0. Per OAuth 1.0, il connettore supporta l'applicazione privata Xero ma non l'applicazione pubblica.
Tutte le tabelle di Xero (endpoint dell'API), ad eccezione di "Reports".

Introduzione

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

Creare un servizio collegato a Xero usando l'interfaccia utente

Usare la procedura seguente per creare un servizio collegato a Xero 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 Xero e selezionare il connettore Xero.
Configurare i dettagli del servizio, testare la connessione e creare il nuovo servizio collegato.

Dettagli di configurazione di Connessione or

Le sezioni seguenti riportano informazioni dettagliate sulle proprietà che vengono usate per definire entità di Data Factory specifiche per il connettore Xero.

Proprietà del servizio collegato

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

Proprietà	Descrizione	Richiesto
Tipo	La proprietà type deve essere impostata su Xero	Sì
connectionProperties	Gruppo di proprietà che definisce come connettersi a Xero.	Sì
In `connectionProperties`:
host	Endpoint del server Xero (`api.xero.com`).	Sì
authenticationType	I valori consentiti sono `OAuth_2.0` e `OAuth_1.0`.	Sì
consumerKey	Per OAuth 2.0, specificare l'ID client per l'applicazione Xero. Per OAuth 1.0, specificare la chiave consumer associata all'applicazione Xero. Contrassegnare questo campo come SecureString per archiviarlo in modo sicuro o fare riferimento a un segreto archiviato in Azure Key Vault.	Sì
privateKey	Per OAuth 2.0, specificare il segreto client per l'applicazione Xero. Per OAuth 1.0, specificare la chiave privata dal file pem generato per l'applicazione privata Xero. Si noti che per generare privatekey.pem con numbit di 512 usando `openssl genrsa -out privatekey.pem 512`, 1024 non è supportato. Includere tutto il testo dal file con estensione pem, incluse le terminazioni riga Unix (\n): vedere l'esempio seguente. Contrassegnare questo campo come SecureString per archiviarlo in modo sicuro o fare riferimento a un segreto archiviato in Azure Key Vault.	Sì
tenantId	ID tenant associato all'applicazione Xero. Applicabile per l'autenticazione OAuth 2.0. Informazioni su come ottenere l'ID tenant dalla sezione Controllare i tenant a cui si è autorizzati ad accedere.	Sì per l'autenticazione OAuth 2.0
refreshToken	Applicabile per l'autenticazione OAuth 2.0. Il token di aggiornamento OAuth 2.0 è associato all'applicazione Xero e usato per aggiornare il token di accesso; il token di accesso scade dopo 30 minuti. Informazioni sul funzionamento del flusso di autorizzazione Xero e su come ottenere il token di aggiornamento da questo articolo. Per ottenere un token di aggiornamento, è necessario richiedere l'ambito offline_access. Limitazione delle conoscenze: Xero reimposta il token di aggiornamento dopo che viene usato per l'aggiornamento del token di accesso. Per il carico di lavoro operativo, prima dell'esecuzione di ogni attività di copia, è necessario impostare un token di aggiornamento valido da usare per il servizio. Contrassegnare questo campo come SecureString per archiviarlo in modo sicuro o fare riferimento a un segreto archiviato in Azure Key Vault.	Sì per l'autenticazione OAuth 2.0
useEncryptedEndpoints	Specifica se gli endpoint dell'origine dati vengono crittografati tramite HTTPS. Il valore predefinito è true.	No
useHostVerification	Specifica se il nome host è necessario nel certificato del server in modo che corrisponda al nome host del server durante la connessione tramite TLS. Il valore predefinito è true.	No
usePeerVerification	Specifica se verificare l'identità del server durante la connessione tramite TLS. Il valore predefinito è true.	No

Esempio: Autenticazione OAuth 2.0

{
    "name": "XeroLinkedService",
    "properties": {
        "type": "Xero",
        "typeProperties": {
            "connectionProperties": { 
                "host": "api.xero.com",
                "authenticationType":"OAuth_2.0", 
                "consumerKey": {
                    "type": "SecureString",
                    "value": "<client ID>"
                },
                "privateKey": {
                    "type": "SecureString",
                    "value": "<client secret>"
                },
                "tenantId": "<tenant ID>", 
                "refreshToken": {
                    "type": "SecureString",
                    "value": "<refresh token>"
                }, 
                "useEncryptedEndpoints": true, 
                "useHostVerification": true, 
                "usePeerVerification": true
            }            
        }
    }
}

Esempio: Autenticazione OAuth 1.0

{
    "name": "XeroLinkedService",
    "properties": {
        "type": "Xero",
        "typeProperties": {
            "connectionProperties": {
                "host": "api.xero.com", 
                "authenticationType":"OAuth_1.0", 
                "consumerKey": {
                    "type": "SecureString",
                    "value": "<consumer key>"
                },
                "privateKey": {
                    "type": "SecureString",
                    "value": "<private key>"
                }, 
                "useEncryptedEndpoints": true,
                "useHostVerification": true,
                "usePeerVerification": true
            }
        }
    }
}

Valore di chiave privata di esempio:

Includere tutto il testo dal file con estensione pem, incluse le terminazioni riga Unix (\n).

"-----BEGIN RSA PRIVATE KEY-----\nMII***************************************************P\nbu****************************************************s\nU/****************************************************B\nA*****************************************************W\njH****************************************************e\nsx*****************************************************l\nq******************************************************X\nh*****************************************************i\nd*****************************************************s\nA*****************************************************dsfb\nN*****************************************************M\np*****************************************************Ly\nK*****************************************************Y=\n-----END RSA PRIVATE KEY-----"

Proprietà del set di dati

Per un elenco completo delle sezioni e delle proprietà disponibili per la definizione di set di dati, vedere l'articolo sui set di dati. Questa sezione presenta un elenco delle proprietà supportate dal set di dati Xero.

Per copiare dati da Xero, impostare la proprietà type del set di dati su XeroObject. Sono supportate le proprietà seguenti:

Proprietà	Descrizione	Richiesto
Tipo	La proprietà type del set di dati deve essere impostata su: XeroObject	Sì
tableName	Nome della tabella.	No (se nell'origine dell'attività è specificato "query")

Esempio

{
    "name": "XeroDataset",
    "properties": {
        "type": "XeroObject",
        "typeProperties": {},
        "schema": [],
        "linkedServiceName": {
            "referenceName": "<Xero linked service name>",
            "type": "LinkedServiceReference"
        }
    }
}

Proprietà dell'attività di copia

Per un elenco completo delle sezioni e delle proprietà disponibili per la definizione delle attività, vedere l'articolo sulle pipeline. Questa sezione presenta un elenco delle proprietà supportate dall'origine Xero.

Xero come origine

Per copiare dati da Xero, impostare il tipo di origine nell'attività di copia su XeroSource. Nella sezione origine dell'attività di copia sono supportate le proprietà seguenti:

Proprietà	Descrizione	Richiesto
Tipo	La proprietà type dell'origine dell'attività di copia deve essere impostata su XeroSource	Sì
query	Usare la query SQL personalizzata per leggere i dati. Ad esempio: `"SELECT * FROM Contacts"`.	No (se nel set di dati è specificato "tableName")

Esempio:

"activities":[
    {
        "name": "CopyFromXero",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<Xero input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "XeroSource",
                "query": "SELECT * FROM Contacts"
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

Notare quanto segue quando si specifica la query Xero:

Le tabelle con elementi complessi verranno suddivise in più tabelle. Le transazioni bancarie, ad esempio, hanno una struttura di dati complessa "LineItems" e i dati delle transazioni vengono quindi mappati alla tabella Bank_Transaction e a Bank_Transaction_Line_Items, con Bank_Transaction_ID come chiave esterna per collegarli tra loro.
I dati Xero sono disponibili tramite due schemi: Minimal (impostazione predefinita) e Complete. Lo schema Complete contiene tabelle di chiamate obbligatorie che richiedono dati aggiuntivi (ad esempio, la colonna ID) per poter eseguire la query desiderata.

Le tabelle seguenti contengono le stesse informazioni degli schemi Minimal e Complete. Per ridurre il numero di chiamate API, usare uno schema Minimal (impostazione predefinita).

Bank_Transactions
Contact_Groups
Contacts
Contacts_Sales_Tracking_Categories
Contacts_Phones
Contacts_Addresses
Contacts_Purchases_Tracking_Categories
Credit_Notes
Credit_Notes_Allocations
Expense_Claims
Expense_Claim_Validation_Errors
Fatture
Invoices_Credit_Notes
Invoices_ Prepayments
Invoices_Overpayments
Manual_Journals
Overpayments
Overpayments_Allocations
Pagamenti anticipati
Prepayments_Allocations
Receipts
Receipt_Validation_Errors
Tracking_Categories

Nelle tabelle seguenti è possibile eseguire query solo con lo schema Complete:

Complete.Bank_Transaction_Line_Items
Complete.Bank_Transaction_Line_Item_Tracking
Complete.Contact_Group_Contacts
Complete.Contacts_Contact_ Persons
Complete.Credit_Note_Line_Items
Complete.Credit_Notes_Line_Items_Tracking
Complete.Expense_Claim_ Payments
Complete.Expense_Claim_Receipts
Complete.Invoice_Line_Items
Complete.Invoices_Line_Items_Tracking
Complete.Manual_Journal_Lines
Complete.Manual_Journal_Line_Tracking
Complete.Overpayment_Line_Items
Complete.Overpayment_Line_Items_Tracking
Complete.Prepayment_Line_Items
Complete.Prepayment_Line_Item_Tracking
Complete.Receipt_Line_Items
Complete.Receipt_Line_Item_Tracking
Complete.Tracking_Category_Options

Proprietà dell'attività Lookup

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

Per un elenco di archivi dati supportati dall'attività di copia, vedere Archivi dati supportati.