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

發行項
11/05/2024

適用於：Azure Data Factory Azure Synapse Analytics

提示

試用 Microsoft Fabric 中的 Data Factory，這是適用於企業的全方位分析解決方案。 Microsoft Fabric 涵蓋從資料移動到資料科學、即時分析、商業智慧和報告的所有項目。了解如何免費開始新的試用！

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

注意

Xero 連接器需要 OAuth 驗證，且不適用於伺服器對伺服器使用。

支援的功能

此 Xero 連接器支援下列功能：

支援的功能	IR
複製活動 (來源/-)	（1）（2）
查閱活動	（1）（2）

① Azure 整合執行階段 ② 自我裝載整合執行階段

如需支援做為來源/接收器的資料存放區清單，請參閱支援的資料存放區表格。

具體而言，這個 Xero 連接器支援：

OAuth 2.0 驗證。
所有 Xero 資料表 (API 端點)，但「報告」除外。
本文中的 Windows 版本。

注意

由於 Xero 中 OAuth 1.0 驗證的日落，如果您目前使用的是 OAuth 1.0 驗證類型，請升級至 OAuth 2.0 驗證類型。

開始使用

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

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

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

前往 Azure Data Factory 或 Synapse 工作區的 [管理] 索引標籤，選取 [連結服務]，然後按一下 [新增]：
- Azure Data Factory
- Azure Synapse
搜尋 Xero 並選取 Xero 連接器。
設定服務詳細資料，測試連線，然後建立新的連結服務。

連接器設定詳細資料

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

連結服務屬性

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

屬性	描述	必要
type	Type 屬性必須設定為：Xero	Yes
connectionProperties	定義如何連接到 Xero 的屬性群組。	Yes
`connectionProperties` 之下：
host	Xero 伺服器的端點 (`api.xero.com`)。	Yes
authenticationType	允許值為：`OAuth_2.0` 和 `OAuth_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 中儲存的祕密。	Yes
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	Yes
tableName	資料表的名稱。	否 (如果已指定活動來源中的「查詢」)

範例

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

複製活動屬性

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

Xero 作為來源

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

屬性	描述	必要
type	複製活動來源的 type 屬性必須設定為：XeroSource	Yes
query	使用自訂 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_Transaction 和 Bank_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
回條
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

查閱活動屬性

若要了解屬性的詳細資料，請參閱查閱活動。

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

共用方式為

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

支援的功能

開始使用

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

連接器設定詳細資料

連結服務屬性

資料集屬性

複製活動屬性

Xero 作為來源

查閱活動屬性

意見反應

其他資源

共用方式為

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

支援的功能

開始使用

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

連接器設定詳細資料

連結服務屬性

資料集屬性

複製活動屬性

Xero 作為來源

查閱活動屬性

相關內容

意見反應

其他資源