Salin data dari Xero menggunakan Azure Data Factory atau Synapse Analytics

Artikel
12/09/2023

BERLAKU UNTUK:Azure Data Factory Azure Synapse Analytics

Tip

Cobalah Data Factory di Microsoft Fabric, solusi analitik all-in-one untuk perusahaan. Microsoft Fabric mencakup semuanya mulai dari pergerakan data hingga ilmu data, analitik real time, kecerdasan bisnis, dan pelaporan. Pelajari cara memulai uji coba baru secara gratis!

Artikel ini menguraikan cara menggunakan Aktivitas Salin di Azure Data Factory atau saluran Synapse Analytics untuk menyalin data dari Xero. Artikel tersebut dibuat berdasarkan artikel gambaran umum aktivitas salin yang menyajikan gambaran umum aktivitas salin.

Kemampuan yang didukung

Konektor Xero ini didukung untuk kemampuan berikut:

Kemampuan yang didukung	IR
Aktivitas penyalinan (sumber/-)	① ②
Aktivitas pencarian	① ②

① Runtime integrasi Azure ② Runtime integrasi yang dihost sendiri

Untuk daftar penyimpanan data yang didukung sebagai sumber/sink, lihat tabel Penyimpanan data yang didukung.

Secara khusus, konektor Xero ini mendukung:

Autentikasi OAuth 2.0 dan OAuth 1.0. Untuk OAuth 1.0, konektor mendukung aplikasi privat Xero tetapi bukan aplikasi publik.
Semua tabel Xero (titik akhir API) kecuali "Laporan".

Memulai

Untuk melakukan aktivitas Salin dengan alur, Anda dapat menggunakan salah satu alat atau SDK berikut:

Membuat layanan tertaut ke Xero menggunakan UI

Gunakan langkah-langkah berikut untuk membuat layanan tertaut ke Xero di UI portal Azure.

Telusuri ke tab Kelola di ruang kerja Azure Data Factory atau Synapse Anda dan pilih Layanan Tertaut, lalu klik Baru:
- Azure Data Factory
- Azure Synapse
Cari Xero dan pilih konektor Xero.
Konfigurasikan detail layanan, uji koneksi, dan buat layanan tertaut baru.

Detail konfigurasi konektor

Bagian berikut memberikan detail tentang properti yang digunakan untuk menentukan entitas Data Factory khusus untuk konektor Xero.

Properti layanan tertaut

Berikut ini properti yang didukung untuk layanan tertaut Xero:

Properti	Deskripsi	Wajib
jenis	Jenis properti harus diatur ke: Xero	Ya
connectionProperties	Grup properti yang menentukan cara menyambungkan ke Xero.	Ya
Di bawah `connectionProperties`:
tuan rumah	Titik akhir server Xero (`api.xero.com`).	Ya
authenticationType	Nilai yang diizinkan adalah `OAuth_2.0` dan `OAuth_1.0`.	Ya
consumerKey	Untuk OAuth 2.0, tentukan ID klien untuk aplikasi Xero Anda. Untuk OAuth 1.0, tentukan kunci konsumen yang terkait dengan aplikasi Xero. Tandai bidang ini sebagai SecureString untuk menyimpannya dengan aman, atau mereferensikan rahasia yang disimpan di Azure Key Vault.	Ya
privateKey	Untuk OAuth 2.0, tentukan rahasia klien untuk aplikasi Xero Anda. Untuk OAuth 1.0, tentukan kunci privat dari file .pem yang dihasilkan untuk aplikasi privat Xero Anda. Catatan untuk menghasilkan privatekey.pem dengan numbits 512 menggunakan `openssl genrsa -out privatekey.pem 512`, 1024 tidak didukung. Sertakan semua teks dari file .pem termasuk akhiran baris Unix(\n), lihat sampel di bawah ini. Tandai bidang ini sebagai SecureString untuk menyimpannya dengan aman, atau mereferensikan rahasia yang disimpan di Azure Key Vault.	Ya
tenantId	ID penyewa yang terkait dengan aplikasi Xero Anda. Berlaku untuk autentikasi OAuth 2.0. Pelajari cara mendapatkan ID penyewa dari Periksa penyewa yang disahkan untuk Anda akses bagiannya.	Ya untuk autentikasi OAuth 2.0
refreshToken	Berlaku untuk autentikasi OAuth 2.0. Token refresh OAuth 2.0 dikaitkan dengan aplikasi Xero dan digunakan untuk merefresh token akses; token akses kedaluwarsa setelah 30 menit. Pelajari tentang cara kerja alur otorisasi Xero dan cara mendapatkan token refresh dari artikel ini. Untuk mendapatkan token refresh, Anda harus meminta cakupan offline_access. Ketahui batasan: Catatan Xero mengatur ulang token refresh setelah digunakan untuk mengakses refresh token. Untuk beban kerja yang dioperasionalkan, sebelum masing-masing aktivitas penyalinan berjalan, Anda perlu mengatur token refresh yang valid untuk digunakan layanan. Tandai bidang ini sebagai SecureString untuk menyimpannya dengan aman, atau mereferensikan rahasia yang disimpan di Azure Key Vault.	Ya untuk autentikasi OAuth 2.0
useEncryptedEndpoints	Menentukan apakah titik akhir sumber data dienkripsi menggunakan HTTPS. Nilai defaultnya adalah true.	Tidak
useHostVerification	Tentukan apakah nama host diperlukan di sertifikat server agar sesuai dengan nama host server saat menyambungkan melalui TLS. Nilai defaultnya adalah true.	Tidak
usePeerVerification	Menentukan apakah akan memverifikasi identitas server ketika menyambungkan melalui TLS. Nilai defaultnya adalah true.	Tidak

Contoh: autentikasi 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
            }            
        }
    }
}

Contoh: autentikasi 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
            }
        }
    }
}

Sampel nilai kunci privat:

Sertakan semua teks dari file .pem termasuk akhiran baris 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-----"

Properti himpunan data

Untuk daftar lengkap bagian dan properti yang tersedia untuk menentukan himpunan data, lihat artikel himpunan data. Bagian ini menyediakan daftar properti yang didukung oleh himpunan data Xero.

Untuk menyalin data dari Xero, atur properti jenis himpunan data ke XeroObject. Berikut adalah properti yang didukung:

Properti	Deskripsi	Wajib
jenis	Properti jenis himpunan data harus diatur ke: XeroObject	Ya
tableName	Nama tabel.	Tidak (jika "kueri" di sumber aktivitas ditentukan)

Contoh

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

Properti aktivitas salin

Untuk daftar lengkap bagian dan properti yang tersedia untuk menentukan aktivitas, lihat artikel Alur. Bagian ini menyediakan daftar properti yang didukung oleh sumber Xero.

Xero sebagai sumber

Untuk menyalin data dari Xero, atur jenis sumber dalam aktivitas salin ke XeroSource. Berikut ini properti yang didukung di bagian sumber aktivitas salin:

Properti	Deskripsi	Wajib
jenis	Properti jenis sumber aktivitas penyalinan harus diatur ke: XeroSource	Ya
pertanyaan	Gunakan kueri SQL kustom untuk membaca data. Sebagai contoh: `"SELECT * FROM Contacts"`.	Tidak (jika "tableName" di himpunan data ditentukan)

Contoh:

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

Perhatikan hal berikut saat menentukan kueri Xero:

Tabel dengan item kompleks akan dibagi menjadi beberapa tabel. Misalnya, transaksi Bank memiliki struktur data yang kompleks "LineItems", sehingga data transaksi bank dipetakan ke tabel Bank_Transaction dan Bank_Transaction_Line_Items, dengan Bank_Transaction_ID sebagai kunci asing untuk menghubungkannya bersama-sama.
Data Xero tersedia melalui dua skema: Minimal (default) dan Complete. Skema Lengkap berisi tabel panggilan prasyarat yang memerlukan data tambahan (misalnya kolom ID) sebelum membuat kueri yang diinginkan.

Tabel berikut memiliki informasi yang sama dalam skema Minimal dan Lengkap. Untuk mengurangi jumlah panggilan API, gunakan skema Minimal (default).

Bank_Transactions
Contact_Groups
Kontak
Contacts_Sales_Tracking_Categories
Contacts_Phones
Contacts_Addresses
Contacts_Purchases_Tracking_Categories
Credit_Notes
Credit_Notes_Allocations
Expense_Claims
Expense_Claim_Validation_Errors
Faktur
Invoices_Credit_Notes
Invoices_ Prepayments
Invoices_Overpayments
Manual_Journals
Lebih bayar
Overpayments_Allocations
Pembayaran di muka
Prepayments_Allocations
Tanda Terima
Receipt_Validation_Errors
Tracking_Categories

Tabel berikut ini hanya bisa dikueri dengan skema lengkap:

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

Properti aktivitas pencarian

Untuk mempelajari detail tentang properti, lihat Aktivitas pencarian.

Untuk daftar penyimpanan data yang didukung oleh aktivitas penyalinan, lihat penyimpanan data yang didukung.