跳至主要內容
文件
文件
Adaptive Planning
上次更新時間 ：2024-09-20
importStandardData

importStandardData

在 API v40 (2024 年 9 月 13 日) 中更新
種類
資料提交
說明
插入或取代標準科目中的資料。
調用所需權限
匯入至所有地點
清除資料 (API v36+ 以支援取代模式)
要求時必填參數
Credentials、ImportDataOptions、Version、RowData
此方法的要求包含的參數將用來決定哪個版本會接收提供的資料列。無論帳戶是否已放在工作表上，都可以將資料匯入至任何標準帳戶 (總分類帳帳戶、自訂帳戶、假設或匯率)。
importStandardData 無法彙入至使用
資料輸入
 進行
覆寫公式設定的
科目。

要求格式


<?xml version='1.0' encoding='UTF-8'?>
<call method="importStandardData" callerName="a string that identifies your client application">
<credentials login="sampleuser@company.com" password="my_pwd" instanceCode="INSTANCE1"/>
<importDataOptions planOrActuals="Plan" allowParallel="false" moveBPtr="false" useMappings="false" />
<version name="Budget 2004" isDefault="false" />
<rowData>
<header>Account|Level|Split Label|Product|Region|11/2005|01/2006</header>
<rows>
  <row>70110|Corporate Plan||Bunnyrabbit Toy|Western-US|2037|4032</row>
</rows>
</rowData>
</call>
此 API 呼叫的每次呼叫都必須包含下列每種類型中的一個元素︰
  • 憑證
  • importDataOptions
  • 版本
  • rowData
  • 標頭
  • 列
如果標頭中的豎線字元 ( | ) 數與資料不符，將會導致 API v30 或更高版本發生錯誤。
對於 API v36+，如果 importDataOptions 模式屬性內容為 REPLACE，則還必須指定範圍元素︰
範例︰取代模式要求
僅適用於 API v36+
 

<?xml version='1.0' encoding='UTF-8'?>
<call method="importStandardData" callerName="a string that identifies your client application">
<credentials login="nobody@company.com" password="password" instanceCode="INSTANCE1"/>
<importDataOptions planOrActuals="Plan" allowParallel="true" moveBPtr="false" useMappings="false" mode="replace" />
<version name="Budget 2011" isDefault="false" />
<scope>
<accounts mode="explicit">
 <account includeDescendants="false">30490</account>
 <account includeDescendants="false">70313</account>
</accounts>
<levels mode="explicit">
<level includeDescendants="false">Development</level>
<level includeDescendants="true">Sales</level>
</levels>
<time mode="input" />
</scope>
<rowData>
<header>Account|Level|Split Label|Base Pay|CapitalAssetClass|Company|CountryRegion|01/2011</header>
<rows>
<row>30490|Asia Sales||120-150K|Furniture|ABC Cons|Washington|1</row>
<row>70313|Development||100-120K|OtherEquipment|ABC Cons|Maharashtra|2</row>
</rows>
</rowData>
</call>
credentials 元素
標記名稱
憑證
說明
所有 API 呼叫都必須包含單一credentials 元素，以識別調用 API 的使用者。然後會以此使用者的身分執行 API 呼叫 (系統中的任何稽核軌跡或動作記錄都會顯示此使用者執行了動作)，因此使用者必須具有執行動作所需的權限，才能讓 API 呼叫針對成功。
元素的屬性
屬性內容名稱
EOI？
值
範例
登入
是
調用 API 方法的使用者的登入名稱。此使用者必須具有必要的權限，才能調用該方法。
sampleuser@company.com
密碼
是
調用 API 方法的使用者的密碼。
my_password
地區設定
否
指定用來解釋傳入數字和日期，以及傳出數字和日期格式的地區設定 (使用適當的千分位分隔符號、時段名稱和日期格式)。地區設定也可用來指定回應中任何系統訊息的顯示語言。如果未指定，則會使用 en_US (美式英語)。
fr_FR
instanceCode
否
如果憑證中指定的使用者有權存取的多個實例
Adaptive Planning
，此屬性內容可用於指定使用者要存取其預設實例以外的實例。如果未指定，則會使用使用者的預設實例。若要確定可用的實例代碼，請使用 exportInstances API。
MYINSTANCE1
元素內容
(無)
importDataOptions 元素
標記名稱
importDataOptions
說明
指定執行匯入時要使用的選項。
元素的屬性
屬性內容名稱
EOI？
值
範例
planOrActuals
是
設為其中一個 "計畫" 或 "實際值”，以指定要匯入的資料類型。如果此設定與版本標記優先使用版本標記的值，並忽略此設定。
計畫
moveBPtr
否
僅在以下情況使用planOrActuals 屬性內容設為實際值如果moveBPtr 設為若為 True，匯入時會將實際值版本中的實際值可用性指針移至匯入資料中的最新時段。如果設為False，則匯入不會影響在任何版本上顯示實際值的時段。如果出現以下情況，則必須將此屬性內容設為 FalseplanOrActuals 設為計畫
false
allowParallel
是
僅在以下情況使用planOrActuals 屬性內容設為實際值如果設為True，則即使此實例已有另一個實際值或交易匯入正在進行中，匯入也會繼續進行。如果設為False，則如果此實例已有正在處理的實際值或交易匯入，則嘗試匯入將會失敗。
false
useMappings
否
指定是否要對列元素內的科目、計畫和維度值使用匯入對應。已考慮預設為 True。如果False，則應使用內部 ID︰科目由代碼識別，層級和維度值由名稱識別。
false
includeContext
否
指定訊息是否可包含環境定義區塊。值為False (從不顯示環境定義) 或True (若適用則顯示環境定義)。如果未指定，假設為 True。
false
displayNameEnabled
僅在 API v30+ 中適用於啟用顯示名稱的實例。
否
displayNameEnabled=true 表示應有 importStandardData
Account Code
,
Level Code
,
Dimension Code
, 和
Dimension Name Column
 於實例的「啟用顯示名稱」設為開啟時，載入於承載資料中。
displayNameEnabled=false 表示即使在實例的「啟用顯示名稱」設為開啟時，importStandardData API 也應繼續遵循 v30 之前的 API 協定。importStandardData API 會忽略顯示名稱屬性
Account Code
,
Level Code
,
Dimension Code
, 和
Dimension Name Column
。
displayNameEnabled 的預設值為「False」。
false
splitsToUnsplit
僅適用於 API v40+
否
splitsToUnsplit=true 允許將拆分匯入包含現有資料的未拆分位置。此屬性內容的預設值為 False。
false
模式
僅適用於 API v36+
否
指定匯入模式，即附加或取代。
附加
現有事實已更新，或已新增事實。不會刪除任何事實。
取代
要求必須包含表示超級 Cube 座標的範圍元素，在該座標中，資料將取代為承載資料中提供的資料。範圍內任何現有資料，如果在承載資料中沒有相符的座標，則會遭到刪除。
API v36 及更高版本開始支援此模式屬性內容。以模式="REPLACE" 呼叫較早版本的 API 會發生錯誤。
未指定時，模式的預設值為 APPEND。
附加
元素內容
(無)
版本元素
標記名稱
版本
說明
指出應使用哪個版本來接收要求的資料。必須為每個呼叫提供版本。
元素的屬性
屬性內容名稱
EOI？
值
範例
名稱
否
用來接收資料的版本名稱。在單一 API 呼叫中只能存取一個版本。如果未提供名稱，則 必須在此元素上將 isDefault 標幟設為 True。
若要取得已換算貨幣版本及其名稱的清單，請在 include 元素中提出exportVersions 要求，並指定 currencyVersions=true。
2014 年度預算
isDefault
否
如果呼叫者無論實例名稱為何都希望存取實例的目前預設版本，可將此屬性內容設為 True，在這種情況下，會忽略標記的名稱屬性內容 (如果有)。否則，如果此值為 False 或此屬性內容不存在，則必須存在具有所提供名稱的版本，且使用者可存取此版本才能成功執行此呼叫。
false
元素內容
(無)
範圍元素
標記名稱
範圍
僅適用於 API 版本 36 以上
說明
指定此匯入的範圍。
僅當 importDataOptions 元素的模式屬性內容為 REPLACE 時才允許。
元素的屬性
屬性內容名稱
EOI？
值
範例
eraseCellNotes
否
指定是否要清除範圍中的儲存格附註。必須是 3 個列舉值之一︰
無
 - 不清除儲存格附註。
全部
 - 清除範圍內的所有儲存格附註。
MODIFIED_ONLY
- 清除範圍內因匯入而修改的儲存格附註。這包括先前已匯入事實的空白儲存格，以及已清除事實的儲存格。
如果未指定 eraseCellNotes，則預設為「無」。
無
元素內容
1 個
時間
 元素、一個
科目
 元素和一個
層級
 元素，皆為必填元素。
科目元素
標記名稱
科目
僅適用於 API 版本 36 以上
說明
指定匯入範圍的科目。如果指定的科目存在，但匯入資料中沒有此科目的資料，則會移除此科目中該時間範圍和其餘範圍座標的資料。
僅當 importDataOptions 元素的模式屬性內容為 REPLACE 時才允許。
元素的屬性
屬性內容名稱
EOI？
值
範例
模式
是
指定科目範圍的模式。必須是下列三個選項之一。
EXPLICIT
- 如果指定此模式，我們預期會看到一或多個科目子元素，這些元素將決定匯入的科目範圍。
輸入
 - 指定此模式後，科目範圍將由匯入資料中存在的唯一科目集決定。
注意︰標準匯入範圍不允許科目模式 =「全部」。
顯式
元素內容
如果模式為
INPUT
，則不能有任何 <account> 子元素。
如果模式為
EXPLICIT
，則必須有一或多個 <account> 子元素。
如果模式為
EXPLICIT
，且 <account> 子元素中的任何科目代碼無效，則將視為整個 <accounts> 元素 (進而延伸至 <scope>) 無效。每個無效代碼的回應中都會包含錯誤訊息。
科目元素
標記名稱
科目
僅適用於 API 版本 36 以上
說明
指定要包含在匯入範圍中的科目代碼。
僅當 importDataOptions 元素的模式屬性內容為 REPLACE 時才允許。
元素的屬性
屬性內容名稱
EOI？
值
範例
includeDescendants
否
如果科目是分葉科目，則 includeDescendants 無效。
如果科目是父系科目，則將此屬性內容指定為 True，將會在範圍內包含此科目的所有分葉後代。
如果科目為父系科目且 includeDescendants 為 False，則發生錯誤。我們只能匯入分葉科目。
這是選填屬性內容，預設值將被視為 False。
True
元素內容
做為匯入範圍一部分的科目，其科目代碼區分大小寫。例如，應付帳款。代碼不可為空白，且代碼對應的科目必須存在。科目不能是系統科目或來源連結科目。如果科目是計算科目，則該科目必須有資料輸入覆寫，否則視為無效。
如果科目代碼無效，則整個 <accounts> 元素 (進而延伸至 <scope>) 都會被視為無效。
層級元素
標記名稱
層級
僅適用於 API 版本 36 以上
說明
指定匯入範圍的層級代碼。如果在此指定了層級代碼，但匯入資料中沒有此層級的資料，則會移除此層級中該時間範圍和其餘範圍座標的資料。
僅當 importDataOptions 元素的模式屬性內容為 REPLACE 時才允許。
元素的屬性
屬性內容名稱
EOI？
值
範例
模式
是
指定層級範圍的模式。必須是下列三個選項之一。
EXPLICIT
- 如果指定此模式，我們預期會看到一或多個 <level> 子元素，這些元素可決定匯入的層級範圍。
輸入
 - 指定此模式後，層級範圍將由匯入資料中存在的唯一層級集決定。
全部
 - 指定此模式後，層級範圍將是所有可匯入的層級。
顯式
元素內容
如果模式為 INPUT 或 ALL，則不能有任何 <level> 子元素。
如果模式為 EXPLICIT，則必須有一或多個 <level> 子元素。
如果模式為 EXPLICIT，且 <level> 子元素中有任何層級代碼無效，則將視為整個 <levels> 元素 (進而延伸至 <scope>) 無效。每個無效代碼的回應中都會包含錯誤訊息。
層級元素
標記名稱
層級
僅適用於 API 版本 36 以上
說明
指定要包含在匯入範圍中的層級代碼。
僅當 importDataOptions 元素的模式屬性內容為 REPLACE 時才允許。
元素的屬性
屬性內容名稱
EOI？
值
範例
includeDescendants
否
如果該層級是父系層級，則將此屬性內容指定為 True，將會包含此層級的所有分葉後代，包括範圍中的該層級本身 (Only 節點)。
這是選填屬性內容。
如果未提供屬性內容，則預設值為 False。如果未提供屬性內容，或提供為 False，且指定的層級是父系層級，則表示匯入會將該層級的「僅限 (例如「僅限工程」) 節點納入範圍。除非其他層級元素明確指定，否則該層級的子係不會包含在範圍內。
True
元素內容
指定層級的代碼 (區分大小寫)。例如，<level>Development</level>。
如果層級代碼有問題，例如在層級找不到代碼，則整個 <levels> 以及延伸的 <scope> 都會被視為無效。每個無效代碼的回應中都會包含錯誤訊息。
時間元素
標記名稱
time
僅適用於 API 版本 36 以上
說明
指定一或多個時間範圍，以表示匯入的時間範圍。
僅當 importDataOptions 元素的模式屬性內容為 REPLACE 時才允許。
元素的屬性
屬性內容名稱
EOI？
值
範例
模式
是
指定時間範圍的模式。應為下列三個選項之一。
輸入
 - 指定此模式後，時間範圍將由
<header>
 元素如果標頭包含兩個月，則匯入範圍將為這兩個月。
EXPLICIT
- 如果已指定此模式，我們預期會看到一或多個 timeRange 子元素，這些元素可決定匯入的時間範圍。
版本
 - 指定此模式後，時間範圍將是版本的開始和結束，包括任何初始餘額期間。
如果模式為 INPUT 或 VERSION，則不允許使用 timeRange 子元素。如果存在 timeRange 子元素，則會被視為錯誤。
輸入
元素內容
一或多個 timeRange 元素，除非模式為 INPUT 或 VERSION。
timeRange 元素
標記名稱
timeRange
僅適用於 API 版本 36 以上
說明
指定時間範圍的單一時間範圍。
僅當 importDataOptions 元素的模式屬性內容為 REPLACE 時才允許。
元素的屬性
屬性內容名稱
EOI？
值
範例
開始
是
匯入時間範圍的開始期間。
07/2021
結束
是
匯入時間範圍的結束期間。
08/2021
元素內容
一或多個 timeRange 元素，除非模式為 INPUT 或 VERSION。
rowData 元素
標記名稱
rowData
說明
要匯入的資料列的容器。
元素的屬性
(無)
元素內容
正好一個標頭元素且正好一個rows 元素
標頭元素
標記名稱
標頭
說明
指定對應項目中資料的欄名稱和順序。rows 元素
元素的屬性
(無)
元素內容
具有以豎線分隔欄名稱的一行文字。這些欄名稱必須與工作表上維度或欄位的名稱相對應，或是可包含資料的時段代碼。這些欄位與要匯入資料的工作表的「匯入範本」中的欄名稱相同，且各欄標頭之間以垂直橫條或豎線符號分隔。
對於啟用「顯示名稱」的實例，標頭不支援
"<dimension>"
 結合
"<dimension> Name"
 或
"<dimension> Code"
 API v30 或更高版本的 Adaptive Planning 支援的地區設定。
rows 元素
標記名稱
列
說明
一或多個容器列元素
元素的屬性
(無)
元素內容
一項或多項列元素
列元素
標記名稱
列
說明
正在匯入的單列資料
元素的屬性
(無)
元素內容
正在匯入的單列中欄位的資料，每個欄位的值以垂直條或豎線符號分隔。資料欄位的順序必須與標頭元素中各行的順序相同。如果值中的數字使用千分位分隔符號，系統會假設這些數字是要求憑證中指定的地區設定中使用的逗號分隔符號。

回覆格式

以下是標準科目資料匯入成功和失敗的回應範例。

成功範例


<?xml version='1.0' encoding='UTF-8'?>
<response success="true"></response>

失敗 (使用環境定義)


<?xml version='1.0' encoding='UTF-8'?>
<response success="false">
<messages>
    <message key="error-empty-account">
        <context>
            <col header="Account" value="" />
            <col header="Level" value="Corporate Plan" />
            <col header="Split Label" value="" />
            <col header="Product" value="Bunnyrabbit Toy" />
            <col header="Region" value="Western-US" />
            <col header="11/2005" value="2037" />
            <col header="01/2006" value="4032" />

        </context>
  Account cannot be empty on row 1.

    </message>
  </messages>
</response>

失敗 (無環境定義)


<?xml version='1.0' encoding='UTF-8'?>
<response success="false">
<messages>
    <message key="error-empty-account">Account cannot be empty on row 1.</message>

</messages>
</response>
回應元素
標記名稱
回應
元素的屬性
屬性內容名稱
EOI？
值
範例
成功
是
兩者之一True 或false，表示 API 呼叫是否成功。即使是成功的呼叫，其回應中也可能包含警告訊息。
True
元素內容
單項選填messages 元素
訊息元素
標記名稱
訊息
說明
一或多個容器訊息元素
元素的屬性
(無)
元素內容
一項或多項訊息元素
訊息元素
標記名稱
訊息
說明
表示系統正在將訊息傳回呼叫者。「訊息」用於顯示要求未成功時的錯誤訊息、要求成功時的警告訊息，以及成功時的確認訊息。
元素的屬性
屬性內容名稱
EOI？
值
範例
索引鍵
否
指定時，金鑰是識別特定訊息或訊息類型的一種方式，可用於用戶端程式中的自動化錯誤記錄和復原。即使訊息的語言變更，關鍵字在要求的不同地區設定下也不會變更。未來也不太可能因為措辭調整或術語變更而變更索引鍵。
invalid-attributevalueid
元素內容
  1. 訊息的文字。此文字使用要求中指定地區設定的語言 (假設支援地區設定)。文字也可能包含變數資訊，例如已處理的列數，或導致錯誤的特定欄或值。
  2. 選用的環境定義元素。
環境定義元素
標記名稱
context
說明
一或多個col元素的容器。
元素的屬性
屬性內容名稱
EOI？
值
範例
無
元素內容
一或多個col元素
col 元素
標記名稱
欄
說明
表示訊息的環境定義。提供標頭/值對，以便識別產生訊息的列。
元素的屬性
屬性內容名稱
EOI？
值
範例
標頭
是
欄的標頭。
「帳戶」
值
是
欄中的值。
"GL-29482-38233"
元素內容
(無)