importTransactions
種類
| 資料提交 |
說明
| 插入新的交易。 |
調用所需權限
| 匯入 |
要求時必填參數
| Credentials、ImportTransactionsOptions、RowData |
此方法僅適用於您有權存取交易的情況。
您只能在匯入期間刪除交易。如果您想在匯入期間移除所有交易，請考慮匯入一個空白列並刪除其餘資料。
此方法可用於刪除符合特定條件的現有交易列、將新的交易列插入系統，或在一次呼叫中同時執行兩種動作 (即將一組交易列取代為另一組列)。
要求格式
<?xml version='1.0' encoding='UTF-8'?> <call method="importTransactions" callerName="a string that identifies your client application"> <credentials login="sampleuser@company.com" password="my_pwd" instanceCode="INSTANCE1"/> <importTransactionsOptions allowParallel="false" useMappings="false"/> <rowData> <header>Posting Date|Transaction Type|Account|Plan|Transaction Amount</header> <rows> <row>01/02/2011|Invoice|70110|Marketing|100</row> </rows> </rowData> </call>
此 API 呼叫的每次呼叫都必須包含下列每種類型中的一個元素︰
- 憑證
- importTransactionsOptions
- rowData
如果標頭中的豎線字元 ( | ) 數與資料不符，將會導致 API v30 或更高版本發生錯誤。
credentials 元素
| |||
標記名稱
| 憑證 | ||
說明
| 所有 API 呼叫都必須包含單一credentials 元素，以識別調用 API 的使用者。然後會以此使用者的身分執行 API 呼叫 (系統中的任何稽核軌跡或動作記錄都會顯示此使用者執行了動作)，因此使用者必須具有執行動作所需的權限，才能讓 API 呼叫針對成功。 | ||
元素的屬性
| |||
屬性內容名稱
| EOI？
| 值
| 範例
|
登入 | 是 | 調用 API 方法的使用者的登入名稱。此使用者必須具有必要的權限，才能調用該方法。 | sampleuser@company.com |
密碼 | 是 | 調用 API 方法的使用者的密碼。 | my_password |
地區設定 | 否 | 指定用來解釋傳入數字和日期，以及傳出數字和日期格式的地區設定 (使用正確的千分位分隔符號、月份名稱和日期格式)。地區設定也可用來指定回應中任何系統訊息的顯示語言。如果未指定，則會使用 en_US (美式英語)。 | fr_FR |
instanceCode | 否 | 如果憑證中指定的使用者有權存取的多個實例 Adaptive Planning ，此屬性內容可用於指定使用者要存取其預設實例以外的實例。如果未指定，則會使用使用者的預設實例。若要確定可用的實例代碼，請使用 exportInstances API。 | MYINSTANCE1 |
元素內容
| |||
(無) | |||
importTransactionsOptions
元素
| |||
標記名稱
| importTransactionsOptions | ||
說明
| 指定執行匯入時要使用的選項。如果以下至少一項︰deleteStartDate,deleteEndDate，或已指定transactionTypes，則此方法呼叫會嘗試刪除任何符合這些指定條件的現有交易。 | ||
元素的屬性
| |||
屬性內容名稱
| EOI？
| 值
| 範例
|
deleteStartDate | 否 | 如果此方法呼叫旨在刪除某些現有的交易，則此屬性內容會指定要刪除的交易集 (含) 的開始日期。若未指定，則所有交易的日期等於或早於deleteEndDate (且與指定的選填項目之一相符TransactionTypes) 將被刪除。 | 11/01/2012 |
deleteEndDate | 否 | 如果此方法呼叫旨在刪除某些現有的交易，則此屬性內容會指定要刪除的交易集 (含) 的結束日期。若未指定，則所有日期等於或晚於deleteStartDate (且符合指定的選填項目之一TransactionTypes) 將被刪除。 | 12/31/2012 |
交易類型 | 否 | 將要刪除的一組交易類型，以豎線符號分隔。若未指定，則在以下期間內指定的所有交易︰deleteStartDate 和將會刪除 deleteEndDate。如果否deleteStartDate 或如果指定了 deleteEndDate，則無論交易的日期為何，都會刪除指定類型的所有交易。 | 發票|採購單 |
allowParallel | 是 | 如果設為True，則即使此實例已有另一個實際值或交易匯入正在進行中，匯入也會繼續進行。如果設為False，則如果此實例已有正在處理的實際值或交易匯入，則嘗試匯入將會失敗。 | false |
useMappings | 否 | 指定是否要對列元素內的科目、計畫和維度值使用匯入對應。已考慮預設為 True。如果False，則應使用內部 ID︰科目由代碼識別，層級和維度值由名稱識別。 | false |
includeContext | 否 | 指定訊息是否可包含環境定義區塊。值為False (從不顯示環境定義) 或True (若適用則顯示環境定義)。如果未指定，假設為 True。 | false |
displayNameEnabled
僅適用於 API v31+，適用於啟用顯示名稱的實例。 | 否 | displayNameEnabled=true 表示當實例的「啟用顯示名稱」設定為開啟時，API 應預期承載資料中的「科目代碼」、「層級代碼」、「維度代碼」和「維度名稱」欄。 displayNameEnabled=false 表示即使在實例的「啟用顯示名稱」設定為開啟時，API 也應繼續遵循 v30 之前的 API 合約。 displayNameEnabled 的預設值為「False」。 | false |
元素內容
| |||
(無) | |||
rowData element
| |||
標記名稱
| rowData | ||
說明
| 要匯入的資料列的容器。 | ||
元素的屬性
| |||
(無) | |||
元素內容
| |||
正好一個標頭元素且正好一個rows 元素 | |||
標頭元素
| |||
標記名稱
| 標頭 | ||
說明
| 指定對應項目中資料的欄名稱和順序。rows 元素 | ||
元素的屬性
| |||
(無) | |||
元素內容
| |||
具有以豎線分隔欄名稱的一行文字。這些欄名稱必須對應於工作表上維度或欄位的名稱，或是可包含資料的月份。這些欄位與要匯入資料的工作表的「匯入範本」中的欄名稱相同，且各欄標頭之間以垂直橫條或豎線符號分隔。
對於啟用「顯示名稱」的實例，標頭不支援 "<dimension>" 結合 "<dimension> Name" 或 "<dimension> Code" API v30 或更高版本的 Adaptive Planning 支援的地區設定。 | |||
rows 元素
| |||
標記名稱
| 列 | ||
說明
| 一或多個容器列元素 | ||
元素的屬性
| |||
(無) | |||
元素內容
| |||
一項或多項列元素 | |||
列元素
| |||
標記名稱
| 列 | ||
說明
| 正在匯入的單列資料 | ||
元素的屬性
| |||
(無) | |||
元素內容
| |||
正在匯入的單列中欄位的資料，每個欄位的值以垂直條或豎線符號分隔。資料欄位的順序必須與標頭元素中各行的順序相同。如果值中的數字使用千分位分隔符號，系統會假設這些數字是要求憑證中指定的地區設定中使用的逗號分隔符號。 | |||
回覆格式
以下是交易資料匯入成功和失敗的回應範例。
成功範例
<?xml version='1.0' encoding='UTF-8'?> <response success="true"> <messages> <message key="row-imported">1 row was imported.</message> </messages> </response>
失敗 (使用環境定義)
<?xml version='1.0' encoding='UTF-8'?> <response success="false"> <messages> <message key="error-import">Import Failed with the following error: No transactions were imported or deleted during the import.</message> <message key="import-detail">Additional information:</message> <message key="warning-nonexistent-dimension-value">Warning: No data was imported for rows with the following dimension values because the dimension values for Transaction Type do not exist: Invoice12.</message> <message key="invalid-dimension-choice-withCoordinate"> <context> <col header="Posting Date" value="01/02/2011" /> <col header="Transaction Type" value="Invoice12" /> <col header="Account" value="70110" /> <col header="Plan" value="Marketing" /> <col header="Transaction Amount" value="100.0" /> </context> Invalid Dimension Choice: Invoice12 on row 1 column B </message> </messages> </response>
失敗 (無環境定義)
<?xml version='1.0' encoding='UTF-8'?> <response success="false"> <messages> <message key="error-import">Import Failed with the following error: No transactions were imported or deleted during the import.</message> <message key="import-detail">Additional information:</message> <message key="warning-nonexistent-dimension-value">Warning: No data was imported for rows with the following dimension values because the dimension values for Transaction Type do not exist: Invoice12.</message> <message key="invalid-dimension-choice-withCoordinate">Invalid Dimension Choice: Invoice12 on row 1 column B</message> </messages> </response>
回應元素
| |||
標記名稱
| 回應 | ||
元素的屬性
| |||
屬性內容名稱
| EOI？
| 值
| 範例
|
成功 | 是 | 兩者之一True 或false，表示 API 呼叫是否成功。即使是成功的呼叫，其回應中也可能包含警告訊息。 | True |
元素內容
| |||
單項選填messages 元素 | |||
訊息元素
| |||
標記名稱
| 訊息 | ||
說明
| 一或多個容器訊息元素 | ||
元素的屬性
| |||
(無) | |||
元素內容
| |||
一項或多項訊息元素 | |||
訊息元素
| |||
標記名稱
| 訊息 | ||
說明
| 表示系統正在將訊息傳回呼叫者。「訊息」用於顯示要求未成功時的錯誤訊息、要求成功時的警告訊息，以及成功時的確認訊息。 | ||
元素的屬性
| |||
屬性內容名稱
| EOI？
| 值
| 範例
|
索引鍵 | 否 | 指定時，金鑰是識別特定訊息或訊息類型的一種方式，可用於用戶端程式中的自動化錯誤記錄和復原。即使訊息的語言變更，關鍵字在要求的不同地區設定下也不會變更。未來也不太可能因為措辭調整或術語變更而變更索引鍵。 | invalid-attributevalueid |
元素內容
| |||
| |||
環境定義元素
| |||
標記名稱
| context | ||
說明
| 一或多個col元素的容器。 | ||
元素的屬性
| |||
屬性內容名稱
| EOI？
| 值
| 範例
|
無 | |||
元素內容
| |||
一或多個col元素 | |||
col 元素
| |||
標記名稱
| 欄 | ||
說明
| 表示訊息的環境定義。提供標頭/值對，以便識別產生訊息的列。 | ||
元素的屬性
| |||
屬性內容名稱
| EOI？
| 值
| 範例
|
標頭 | 是 | 欄的標頭。 | 「帳戶」 |
值 | 是 | 欄中的值。 | "GL-29482-38233" |
元素內容
| |||
(無) | |||