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

適用於：Azure Data Factory Azure Synapse Analytics

秘訣

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

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

附註

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

這很重要

Xero 連接器 2.0 版提供改進的原生 Xero 支援。如果您的解決方案中使用 Xero 連接器 1.0 版本，請在 2026 年 3 月 31 日前升級 Xero 連接器。如需 2.0 版與 1.0 版之間的差異詳細資料，請參閱本章節。

支援的功能

此 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 連接器現在支援 2.0 版。請參閱本節，從 1.0 版升級 Xero 聯結器版本。如需屬性詳細資料，請參閱對應的章節。

2.0 版
1.0 版

2.0 版

Xero 連結服務在應用版本 2.0 時支援以下特性：

屬性	描述	必要
型別	Type 屬性必須設定為：Xero	是
版本	您指定的版本。該值為 `2.0`。	是
主持人	Xero 伺服器的端點 (`api.xero.com`)。	是
clientId	指定 Xero 應用程式的用戶端 ID 。將此欄位標記為 SecureString 以便安全儲存，或參考 Azure Key Vault 中儲存的祕密。	是
clientSecret	指定 Xero 應用程式的用戶端密碼。將此欄位標記為 SecureString 以便安全儲存，或參考 Azure Key Vault 中儲存的祕密。	是
tenantId	與 Xero 應用程式相關聯的租用戶識別碼。適用於 OAuth 2.0 驗證。瞭解如何從檢查您有權存取的租用戶區段取得租用戶識別碼。	是
refreshToken	OAuth 2.0 重新整理權杖會與 Xero 應用程式相關聯，並用來重新整理存取權杖；存取權杖會在 30 分鐘後到期。瞭解 Xero 授權流程的運作方式，以及如何從本文取得重新整理權杖。若要取得重新整理權杖，您必須要求 offline_access scope。瞭解限制：注意 Xero 會在用於存取權杖重新整理之後重設重新整理權杖。針對作業化的工作負載，在每次複製活動執行之前，您需要設定有效的重新整理權杖以供服務使用。將此欄位標記為 SecureString 以便安全儲存，或參考 Azure Key Vault 中儲存的祕密。	是
connectVia	用以連接資料存放區的整合執行環境。如果未指定值，此屬性會使用預設的 Azure 整合執行階段。你可以使用自佈建的整合執行時間，其版本號應該是 5.61 或以上。	否

範例︰

{
    "name": "XeroLinkedService",
    "properties": {
        "type": "Xero",
        "version": "2.0",
        "typeProperties": {
            "host": "api.xero.com",
            "clientId": "<client ID>",
            "clientSecret": "<client secret>",
            "tenantId": "<tenant ID>", 
            "refreshToken": {
                "type": "SecureString",
                "value": "<refresh token>"
            },
            "authenticationType":"OAuth_2.0"       
        }
    }
}

1.0 版

Xero 連結服務在應用版本 1.0 時支援以下屬性：

屬性	描述	必要
型別	Type 屬性必須設定為：Xero	是
connectionProperties	定義如何連接到 Xero 的屬性群組。	是
在 `connectionProperties`底下：
主持人	Xero 伺服器的端點 (`api.xero.com`)。	是
authenticationType	允許值為：`OAuth_2.0` 和 `OAuth_1.0`。	是
consumerKey	針對 OAuth 2.0，指定 Xero 應用程式的用戶端識別碼。針對 OAuth 1.0，指定與 Xero 應用程式相關聯的取用者金鑰。將此欄位標記為 SecureString 以便安全儲存，或參考 Azure Key Vault 中儲存的祕密。	是
privateKey	針對 OAuth 2.0，指定 Xero 應用程式的用戶端密碼。針對 OAuth 1.0，指定從 Xero 私人應用程式產生之 .pem 檔案的私密金鑰。使用 `openssl genrsa -out privatekey.pem 512` 備註；不支援 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。	否
useHostVerification	指定在透過 TLS 連線時，是否要求伺服器憑證中的主機名稱符合伺服器的主機名稱。預設值為 true。	否
usePeerVerification	指定在透過 TLS 連線時，是否要驗證伺服器的身分識別。預設值為 true。	否

範例：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。以下是支援的屬性：

屬性	描述	必要
型別	資料集的類型屬性必須設定為：XeroObject	是
表格	資料表的名稱。資料表名稱使用物件名稱，例如： `Accounts`。此特性僅支援於版本 2.0。	是
tableName	資料表的名稱。資料表名稱使用帶有前綴的物件名稱，例如 `"Global"."Accounts"`。此特性僅在版本 1.0 中支援。	否 (如果已指定活動來源中的「查詢」)

範例

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

連接器 2.0 版支援下列 Xero 資料表：

Accounts
銀行交易明細項目
銀行轉帳
Budgets
Contacts_Addresses
Contact_Group_Contacts
Contacts_Phones
Credit_Note_Line_Items
Credit_Notes_Line_Items_Tracking
貨幣
發票明細項目
發票項目追蹤
物品
日記帳
日誌條目
Journal_Line_Tracking_Categories
Manual_Journals
Manual_Journal_Lines
機構
預付款項目
專案
專案使用者
採購訂單項目明細
稅率
Tracking_Categories
追蹤類別選項
使用者

複製活動屬性

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

Xero 作為來源

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

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

附註

query 2.0 版不支援。

範例︰

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

Xero 的資料類型映射

當您從 Xero 複製資料時，下列對應會從 Xero 的資料類型套用至服務所使用的內部資料類型。若要瞭解複製活動如何將來源架構和資料類型映射到匯入端，請參閱架構和資料類型對應。

Xero 資料類型	過渡期服務資料類型 (針對 2.0 版)	過渡期服務資料類型（1.0 版）
繩子	繩子	繩子
Date	繩子	Date
DateTime	繩子	繩子
布林值	布林值	布林值
數字（標準）	Int32	Int32
數字（大）	Int64	Int64

查閱活動屬性

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

Xero 連接器生命週期和升級

下表顯示不同版本 Xero 連接器的發行階段和變更記錄：

版本	發行階段	變更紀錄
1.0 版	已宣佈終止支援	/
2.0 版	GA 版本可用	• 在連結的服務中，`consumerKey` 被取代為 `clientId`，`privateKey` 被取代為 `clientSecret`。 • 在資料集中使用 `table` 而非 `tableName`。 • 的 `table` 值為物件名稱，例如： `Accounts`。 • 自架整合執行版本應為 5.61 或以上。 • 「日期」會讀取為「字串」資料類型。 • 支持特定的 Xero 表。如需支援的資料表清單，請移至資料集屬性。 • `useEncryptedEndpoints`、`useHostVerification`、`usePeerVerification` 在連結服務中不受支援。 • `query` 不受支援。 • 不支援 OAuth 1.0 驗證。

將 Xero 連接器從 1.0 版升級至 2.0 版

在 [編輯鏈接服務 ] 頁面中，選取 2.0 版，並參考鏈接服務屬性 2.0 版來設定連結服務。
Xero 連結服務 2.0 版的資料類型對映與 1.0 版的資料類型對映不同。若要瞭解最新的資料類型對應，請參閱 Xero 的資料類型對應。
如果你使用自架整合執行環境，其版本應該是 5.61 或以上。
用 table 2.0 版本代替 tableName 。詳細設定請前往資料集屬性。
query 僅在 1.0 版中受支持。您應該在 2.0 版中使用 table 而不是 query。
請注意，2.0 版本支援特定的 Xero 表格。如需支援的資料表清單，請移至資料集屬性。

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

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-01-22