Xero

實體、作業和動作

所有整合連接器都為已連結應用程式的物件提供一層抽象層。您只能透過這個抽象層級存取應用程式的物件。抽象概念會以實體、作業和動作的形式提供給您。

• 實體： 實體可視為已連結應用程式或服務中的物件或屬性集合。實體的定義與連接器至連接器的定義不同。舉例來說，在資料庫連接器中，資料表是實體；在檔案伺服器連接器中，資料夾是實體；在訊息系統連接器中，佇列是實體。

  不過，連接器可能不支援或沒有任何實體，在這種情況下，Entities 清單會是空白。

• 作業： 作業是指您可對實體執行的活動。您可以對實體執行下列任一操作：
  • 列出
  • 取得
  • 建立
  • 更新
  • 刪除

  從可用清單中選取實體後，系統會產生可用於該實體的作業清單。如需作業的詳細說明，請參閱連接器工作中的實體作業。不過，如果連接器不支援任何實體作業，則 Operations 清單中不會列出這些不支援的作業。

• 動作： 動作是透過連接器介面提供給整合項目的一流函式。動作可讓您變更實體或多個實體，而這些變更會因連接器而異。通常，動作會有一些輸入參數和輸出參數。不過，連接器可能不支援任何動作，在這種情況下，Actions 清單會為空白。

系統限制

Xero 連接器可處理每個節點每秒 5 筆交易，並節流超出此限制的所有交易。不過，Xero 連接器可處理的交易數量也取決於 Xero 執行個體設定的限制。詳情請參閱「Xero API 使用頻率限制」。根據預設，Integration Connectors 會為連線分配 2 個節點 (可提高可用性)。

如要瞭解 Integration Connectors 適用的限制，請參閱「限制」一節。

動作

本節列出連接器支援的部分動作。如要瞭解如何設定動作，請參閱「動作範例」。

DownloadAttachment 動作

這項操作會下載附件。

DownloadAttachment 動作的輸入參數

DownloadAttachment 動作的輸出參數

如果下載成功，這個動作會傳回狀態 200 (OK)。

如要瞭解如何設定 DownloadAttachment 動作，請參閱「動作範例」。

UploadAttachment 動作

這項動作可讓您上傳附件。

UploadAttachment 動作的輸入參數

UploadAttachment 動作的輸出參數

如果物件上傳成功，這個動作會傳回狀態 200 (OK)。

如要瞭解如何設定 UploadAttachment 動作，請參閱「動作範例」。

ListAttachment 動作

這項操作可讓您列出資料表的所有附件。

ListAttachment 動作的輸入參數

ListAttachment 動作的輸出參數

如果刪除成功，這個動作會傳回狀態 200 (OK)。

如要瞭解如何設定 ListAttachment 動作，請參閱「動作範例」。

SendInvoiceMail 動作

此動作可讓您傳送電子郵件給開立帳單者。

SendInvoiceMail 動作的輸入參數

SendInvoiceMail 動作的輸出參數

如果移動作業成功，此動作會傳回狀態 200 (OK)。

如要瞭解如何設定 SendInvoiceMail 動作，請參閱「動作範例」。

UploadFile 動作

這項動作可讓您上傳檔案。

UploadFile 動作的輸入參數

UploadFile 動作的輸出參數

如果物件上傳成功，這個動作會傳回狀態 200 (OK)。

如要瞭解如何設定 UploadFile 動作，請參閱「動作範例」。

行動號召範例

本節說明如何在這個連接器中執行部分動作。

範例：下載附件

本範例會下載附件。

1. 在 Configure connector task 對話方塊中，按一下 Actions。
2. 選取 DownloadAttachment 動作，然後按一下「Done」。
3. 在「Connectors」任務的「Task Input」部分，按一下 connectorInputPayload，然後在 Default Value 欄位中輸入類似以下的值：

   {
   "Filename": "Xero_Test.txt",
   "Table": "Contacts",
   "ObjectId": "6a92a3ab-87cf-4f2f-8beb-ecb4f8ae4d41"
   }

如果動作成功，DownloadAttachment 工作項的 connectorOutputPayload 回應參數會包含類似以下的值：

[{
"Success": "True",
"Content": "Test content"
}]

範例：上傳附件

這個範例會上傳附件。

1. 在 Configure connector task 對話方塊中，按一下 Actions。
2. 選取 UploadAttachment 動作，然後按一下「Done」。
3. 在「Connectors」任務的「Task Input」部分，按一下 connectorInputPayload，然後在 Default Value 欄位中輸入類似以下的值：

   {
   "Filename": "Xero_Test.txt",
   "ObjectId": "6a92a3ab-87cf-4f2f-8beb-ecb4f8ae4d41",
   "ContentType": "txt",
   "Table": "Contacts",
   "Content": "Test content upload attachment"
   }

如果動作成功，UploadAttachment 工作項的 connectorOutputPayload 回應參數會包含類似以下的值：

[{
"Success": null,
"AttachmentId": "5ba982a6-9294-45a7-bdda-5f134b0d69d5",
"FileName": "Xero_Test.txt",
"URL": "https://api.xero.com/api.xro/2.0/Contacts/6a92a3ab-87cf-4f2f-8bwb-fcb4f8ae4d41/Attachments/Xero_Test.txt",
"MimeType": "text/plain",
"ContentLength": "27",
"IncludeOnline": null,
"_": ""
}, {
"Success": null,
"AttachmentId": null,
"FileName": null,
"URL": null,
"MimeType": null,
"ContentLength": null,
"IncludeOnline": null,
"_": null
}]

範例：列出附件

這個範例會列出指定資料表的附件。

1. 在 Configure connector task 對話方塊中，按一下 Actions。
2. 選取 ListAttachment 動作，然後按一下「Done」。
3. 在「Connectors」任務的「Task Input」部分，按一下 connectorInputPayload，然後在 Default Value 欄位中輸入類似以下的值：

   {
   "ObjectId": "6a92a3ab-87cf-4f2f-8beb-ecb4f8ae4d41",
   "Table": "Contacts"
   }

如果動作成功，ListAttachment 工作項的 connectorOutputPayload 回應參數會包含類似以下的值：

[{
"AttachmentId": "5ba982a6-9294-45a7-bdda-5f134b0d69d5",
"FileName": "Xero_Limit_Testing.txt",
"URL": "https://api.xero.com/api.xro/2.0/Contacts/6a92a3ab-87cf-4f2f-8bwb-fcb4f8ae4d41/Attachments/Xero_Test.txt",
"MimeType": "text/plain",
"ContentLength": "27"
}]

範例：傳送月結單電子郵件

這個範例會傳送指定月結單的電子郵件。

1. 在 Configure connector task 對話方塊中，按一下 Actions。
2. 選取 SendInvoiceMail 動作，然後按一下「Done」。
3. 在「Connectors」任務的「Task Input」部分，按一下 connectorInputPayload，然後在 Default Value 欄位中輸入類似以下的值：

   {
   "InvoiceId": "016a64c7-be0b-45a2-acae-13057fdf1566"
   }

如果動作成功，SendInvoiceMail 工作項的 connectorOutputPayload 回應參數會包含類似以下的值：

[{
"Success": "true"
}]

範例：上傳檔案

這個範例會上傳檔案。

1. 在 Configure connector task 對話方塊中，按一下 Actions。
2. 選取 UploadFile 動作，然後按一下「Done」。
3. 在「Connectors」任務的「Task Input」部分，按一下 connectorInputPayload，然後在 Default Value 欄位中輸入類似以下的值：

   {
   "Name": "Sample1.txt",
   "Content": "This is a sample file"
   }

如果動作成功，UploadFile 工作項的 connectorOutputPayload 回應參數會包含類似以下的值：

[{
"Success": "true",
"FileId": "09039c7b-35a2-473d-aa79-16fe00b8d460",
"Name": "Sample1.txt",
"FolderId": "36e5115d-a9b6-4c22-baf3-40a8b28ee71d",
"MimeType": "text/plain",
"Size": 26.0,
"User_Id": "c1e33cc9-eb61-45cb-9e46-3ea4121cbdc6",
"User_Name": "test_user_1@test.com",
"User_FirstName": "John",
"User_LastName": "Smith",
"User_FullName": "John Smith",
"Created": "2023-12-18 17:38:53.01",
"Updated": "2023-12-18 17:38:53.01"
}]

實體操作範例

本節說明如何在這個連接器中執行部分實體作業。

範例：列出所有記錄

這個範例會列出 Accounts 實體中的所有記錄。

1. 在 Configure connector task 對話方塊中，按一下 Entities。
2. 從 Entity 清單中選取 Accounts。
3. 選取 List 作業，然後按一下「Done」。
4. 您也可以在 Connector 工作中的「Task Input」部分，指定篩選子句來篩選結果集。例如：City='Bangalore'。您也可以使用邏輯運算子指定多個篩選條件。例如：City='Bangalore' and region='asia-south2'。

示例：取得月結單

這個範例會從 Invoices 實體取得指定 ID 的應付憑據。

1. 在 Configure connector task 對話方塊中，按一下 Entities。
2. 從 Entity 清單中選取 Invoices。
3. 選取 Get 運算，然後按一下「Done」。
4. 在「連接器」任務的「任務輸入」部分，按一下「EntityId」，然後在「預設值」欄位中輸入 1|016a64c7-be0b-45a2-acae-13057fdf1566。

   其中 1|016a64c7-be0b-45a2-acae-13057fdf1566 是 Invoices 實體中的主鍵值。

範例：建立帳單

本範例會在 Invoices 實體中建立月結單。

1. 在 Configure connector task 對話方塊中，按一下 Entities。
2. 從 Entity 清單中選取 Invoices。
3. 選取 Create 運算，然後按一下「Done」。
4. 在「Connectors」任務的「Task Input」部分，按一下 connectorInputPayload，然後在 Default Value 欄位中輸入類似以下的值：

   {
   "Type": "ACCPAY",
   "ContactName": "ContactName1",
   "LineItem_Description": "LineItemDescription"
   }

   如果整合成功，連接器工作 connectorOutputPayload 欄位的值會類似以下內容：

   {
   "Id": "1|7b29efe9-dacd-47bb-85a6-0c0640ce25de"
   }

範例：更新記錄

這個範例會更新 AssetTypes 實體中的記錄。

1. 在 Configure connector task 對話方塊中，按一下 Entities。
2. 從 Entity 清單中選取 AssetTypes。
3. 選取 Update 運算，然後按一下「Done」。
4. 在「Connectors」任務的「Task Input」部分，按一下 connectorInputPayload，然後在 Default Value 欄位中輸入類似以下的值：

   {
   "BookDepreciationSetting_DepreciationRate": 10.0
   }

5. 按一下「entityId」，然後在「Default Value」欄位中輸入 f8d43548-25b0-4cc3-8f59-d97106974fe8。

   如果整合成功，連接器工作 connectorOutputPayload 欄位的值會類似以下內容：

   {
   "AssetTypeId": "f8d43548-25b0-4cc3-8f59-d97106974fe8"
   }

範例：刪除檔案

這個範例會從 Files 實體中刪除指定 ID 的檔案。

1. 在 Configure connector task 對話方塊中，按一下 Entities。
2. 從 Entity 清單中選取 Files。
3. 選取 Delete 運算，然後按一下「Done」。
4. 在「連接器」任務的「Task Input」部分，點選「entityId」，然後在「Default Value」欄位中輸入 421c82f0-38fb-4074-a679-63b04c0d8832。