使用 Azure Data Factory 或 Synapse Analytics 從 Xero 複製資料

適用於:Azure Data Factory Azure Synapse Analytics

此文章概述如何使用 Azure Data Factory 或 Synapse Analytics 管線中的複製活動,從 Xero 複製資料。 本文是根據複製活動概觀一文,該文提供複製活動的一般概觀。

支援的功能

此 Xero 連接器支援下列活動:

您可以將資料從 Xero 複製到任何支援的接收資料存放區。 如需複製活動所支援作為來源/接收器的資料存放區清單,請參閱支援的資料存放區表格。

具體而言,這個 Xero 連接器支援:

  • OAuth 2.0 和 OAuth 1.0 驗證。 針對 OAuth 1.0,連接器支援 Xero 私人應用程式,但不支援公用應用程式。
  • 所有 Xero 資料表 (API 端點),但「報告」除外。

開始使用

若要透過管線執行複製活動,您可以使用下列其中一個工具或 SDK:

使用 UI 建立與 Xero 的連結服務

使用下列步驟,在 Azure 入口網站 UI 中建立與 Xero 的連結服務。

  1. 瀏覽至 Azure Data Factory 或 Synapse 工作區中的 [管理] 索引標籤,並選取 [連結服務],然後按一下 [新增]:

  2. 搜尋 Xero 並選取 Xero 連接器。

    Select the Xero connector.

  3. 設定服務詳細資料、測試連線,然後建立新的連結服務。

    Configure a linked service to Xero.

連接器設定詳細資料

下列各節提供屬性的相關詳細資料,這些屬性是用來定義 Xero 連接器專屬的 Data Factory 實體。

連結服務屬性

以下是針對 Xero 已連結服務支援的屬性:

屬性 描述 必要
type Type 屬性必須設定為:Xero Yes
connectionProperties 定義如何連接到 Xero 的屬性群組。 Yes
connectionProperties 底下:
主機 Xero 伺服器的端點 (api.xero.com)。
authenticationType 允許的值為:OAuth_2.0OAuth_1.0 Yes
consumerKey 針對 OAuth 2.0,指定 Xero 應用程式的用戶端識別碼
針對 OAuth 1.0,指定與 Xero 應用程式相關聯的取用者金鑰。
將此欄位標記為 SecureString 以將其安全地儲存,或參考 Azure Key Vault 中儲存的祕密
Yes
privateKey 針對 OAuth 2.0,指定 Xero 應用程式的用戶端密碼
針對 OAuth 1.0,指定從 Xero 私人應用程式產生之 .pem 檔案的私密金鑰。 使用 openssl genrsa -out privatekey.pem 512產生 numbit 為 512 的 privatekey.pem 備註;不支援 1024。 包含 .pem 檔案的所有文字,包括 Unix 行尾結束符號 (\n),請參閱以下範例。

將此欄位標記為 SecureString 以將其安全地儲存,或參考 Azure Key Vault 中儲存的祕密
tenantId 與 Xero 應用程式相關聯的租用戶識別碼。 適用於 OAuth 2.0 驗證。
瞭解如何從檢查您有權存取的租用戶區段取得租用戶識別碼。
適用於 OAuth 2.0 驗證
refreshToken 適用於 OAuth 2.0 驗證。
OAuth 2.0 重新整理權杖會與 Xero 應用程式相關聯,並用來重新整理存取權杖;存取權杖會在 30 分鐘後到期。 瞭解 Xero 授權流程的運作方式,以及如何從本文取得重新整理權杖。 若要取得重新整理權杖,您必須要求 offline_access scope
瞭解限制:注意 Xero 會在用於存取權杖重新整理之後重設重新整理權杖。 針對作業化的工作負載,在每次複製活動執行之前,您需要設定有效的重新整理權杖以供服務使用。
將此欄位標記為 SecureString 以將其安全地儲存,或參考 Azure Key Vault 中儲存的祕密
適用於 OAuth 2.0 驗證
useEncryptedEndpoints 指定是否使用 HTTPS 來加密資料來源端點。 預設值為 true。 No
useHostVerification 指定在透過 TLS 連線時,是否要求伺服器憑證中的主機名稱符合伺服器的主機名稱。 預設值為 true。 No
usePeerVerification 指定在透過 TLS 連線時,是否要驗證伺服器的身分識別。 預設值為 true。 No

範例: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
            }            
        }
    }
}

範例: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
            }
        }
    }
}

範例私密金鑰值:

包含 .pem 檔案的所有文字,包括 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-----"

資料集屬性

如需可用來定義資料集的區段和屬性完整清單,請參閱資料集一文。 本節提供 Xero 資料集所支援的屬性清單。

若要從 Xero 複製資料,請將資料集的 type 屬性設定為 XeroObject。 以下是支援的屬性:

屬性 描述 必要
type 資料集的類型屬性必須設定為:XeroObject
tableName 資料表的名稱。 否 (如果已指定活動來源中的「查詢」)

範例

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

複製活動屬性

如需可用來定義活動的區段和屬性完整清單,請參閱管線一文。 本節提供 Xero 來源所支援的屬性清單。

Xero 作為來源

若要從 Xero 複製資料,請將複製活動中的來源類型設定為 XeroSource。 複製活動的 source 區段支援下列屬性:

屬性 描述 必要
type 複製活動來源的 type 屬性必須設定為:XeroSource
查詢 使用自訂 SQL 查詢來讀取資料。 例如: "SELECT * FROM Contacts" 否 (如果已指定資料集中的 "tableName")

範例︰

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

指定 Xero 查詢時,請注意下列事項:

  • 具有複雜項目的資料表將會分割成多個資料表。 例如,銀行交易有複雜的資料結構 "LineItems",所以銀行交易的資料會對應至資料表 Bank_TransactionBank_Transaction_Line_Items,並以 Bank_Transaction_ID 作為外部索引鍵而連結在一起。

  • Xero 資料可透過兩個結構描述取得:Minimal (預設值) 和 Complete。 Complet 結構描述包含必要呼叫資料表,其在進行所要的查詢之前需有額外的資料 (例如識別碼資料行)。

下表中的 Minimal 和 Complete 結構描述有相同的資訊。 若要減少 API 呼叫數目,請使用 Minimal 結構描述 (預設值)。

  • Bank_Transactions
  • Contact_Groups
  • 連絡人
  • Contacts_Sales_Tracking_Categories
  • Contacts_Phones
  • Contacts_Addresses
  • Contacts_Purchases_Tracking_Categories
  • Credit_Notes
  • Credit_Notes_Allocations
  • Expense_Claims
  • Expense_Claim_Validation_Errors
  • 發票
  • Invoices_Credit_Notes
  • Invoices_Prepayments
  • Invoices_Overpayments
  • Manual_Journals
  • Overpayments
  • Overpayments_Allocations
  • Prepayments
  • Prepayments_Allocations
  • Receipts
  • Receipt_Validation_Errors
  • Tracking_Categories

只有使用 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

查閱活動屬性

若要了解關於屬性的詳細資料,請參閱查閱活動

後續步驟

如需複製活動所支援的資料存放區清單,請參閱支援的資料存放區