importConfigurableModelData
在 API v40 (2024 年 9 月 21 日) 中更新。
種類
| 資料提交 |
說明
| 插入、取代或更新模型工作表中的資料。 |
調用所需權限
| 匯入 |
要求時必填參數
| 憑證、ImportDataOptions、Version、工作表、RowData |
此方法的要求包含的參數將用來決定哪個工作表和版本將接收提供的資料列。
此方法可以︰
- 將新列附加到工作表上。
- 使用匯入內容取代目前在模型工作表上的所有列。
- 僅針對匯入的層級,取代工作表中的所有資料
- 使用匯入索引鍵比對匯入的列,以更新現有的列。
- 將匯入的列與匯入索引鍵比對,以更新現有的列,並新增列。
此 API 呼叫的每次呼叫都必須包含下列每種類型中的一個元素︰
- 憑證
- importDataOptions
- 版本
- 工作表
- rowData
如果標頭中的豎線字元 ( | ) 數與資料不符,將會導致 API v30 或更高版本發生錯誤。
自 API v37 起,我們限制了可匯入模型工作表中的新列數上限。如果您遇到此限制,請聯絡支援人員。
要求格式
<?xml version='1.0' encoding='UTF-8'?> <call method="importConfigurableModelData" 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" replaceExisting="2"/> <version name="Budget 2014" isDefault="false" /> <sheet name="Personnel" isUserAssigned="false" /> <rowData> <header>Level|Region|Title|JobCode|Benefits|per|Last Name|First Name|ID|Start|End|Hr/Week|Pay Rate|Pay Rate Display Column</header> <rows> <row>Corporate Plan|Any|CEO|E1|Yes|Yr|Topdog|Andy|1000|12/20/2013|12/30/2014|80|500,000.12|888,888</row> </rows> </rowData> </call>
使用 importKey 更新現有列的要求格式
<?xml version='1.0' encoding='UTF-8'?> <call method="importConfigurableModelData" callerName="a string that identifies your client application"> <credentials login="sampleuser@company.com" password="my_pwd"instanceCode="INSTANCE1"/> <importDataOptions planOrActuals="Plan" replaceExisting="3" importKey="Region" allowParallel="false" moveBPtr="false" useMappings="false"/> <version name="Budget 2014" isDefault="false" /> <sheet name="Personnel" isUserAssigned="false" /> <rowData> <header>Plan|Region|Benefits|per</header> <rows> <row>Europe Sales|W-US|Yes|Hr</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 | 否 | 僅在所匯入的資料具有每列的一組時間跨度數字時使用。如果moveBPtr 設為若為 True,匯入時會將實際值版本中的實際值可用性指針移至匯入資料中的最新時段。如果設為False,則匯入不會影響在任何版本上顯示實際值的時段。如果 planOrActuals 設為「計畫」,則必須將此屬性內容設為 False。 | false |
allowParallel | 是 | 如果設為True,則即使此實例已有另一個實際值或交易匯入正在進行中,匯入也會繼續進行。如果設為False,則如果此實例已有正在處理的實際值或交易匯入,則嘗試匯入將會失敗。 | false |
useMappings | 否 | 指定是否要對列元素內的科目、計畫和維度值使用匯入對應。已考慮預設為 True。如果False,則應使用內部 ID︰科目由代碼識別,層級和維度值由名稱識別。 | false |
取代現有項目 | 否 | 設為「1」或「true」可使用正在匯入的新列取代所有層級上的所有現有列(即清除所有層級上所有先前存在的列)只有具有 「匯入至所有位置」 權限的使用者才能使用此選項。設為「0」或「False」可將匯入的列附加到現有的列,即使新的列是重複的列也是如此。 設為「2」可使用正在匯入的新列取代模型工作表中的現有列,但僅限於正在匯入的層級。上傳的試算表中沒有任何未拆分列的層級不會移除其現有的列,除非該列是要由上傳資料取代的列的拆分。 replaceExisting 會檢查使用的維度,以及資料是否存在於相同層級、科目、時段和版本中。如有列索引鍵存在,我們也會比對列索引鍵欄。 如果系統中的相同位置有資料存在,則匯入會取代該資料。此取代會逐列進行。匯入不會立即取代所有內容。不相符的匯入列會附加至工作表。 例如,您執行兩次匯入。您的第一個匯入檔案會載入第二個匯入檔案未包含的資料。第二次匯入後,該現有資料會繼續存在。 如果您要刪除特定欄中的所有資料,請包含該欄,但將其欄值保留空白。未提及欄的欄值保持不變。 設為「3」可更新模型工作表中的現有列,以反映正在匯入的新列。如果有任何列與現有的列不符,則會傳回警告。此模式需要 importKey。已選取 允許拆分
設為「4」可更新模型工作表中的現有列,以反映正在匯入的新列,並為與現有列不相符的任何列插入新列。此模式需要 importKey。僅有的必填欄是「匯入索引鍵」、「層級」和任何文字選取器,即使未新增列也是如此。已選取 允許拆分
預設值為 True。 | true |
importKey | 否 | 更新模型工作表列時,做為匯入索引鍵的模型工作表欄名稱。 Adaptive Planning 使用匯入索引欄,將匯入中的每一列比對至模型工作表中的列。每一列的匯入索引鍵值必須是唯一的。此屬性內容僅可在「replaceExisting」為「3」或「4」時使用。 匯入索引欄可以是下列其中一項︰
| 層級 |
includeContext | 否 | 指定訊息是否可包含環境定義區塊。值為False (從不顯示環境定義) 或True (若適用則顯示環境定義)。如果未指定,假設為 True。 | false |
displayNameEnabled
僅適用於 API v31+,適用於啟用顯示名稱的實例。 | 否 | displayNameEnabled=true 表示當實例的「啟用顯示名稱」設定為開啟時,API 應預期承載資料中的「科目代碼」、「層級代碼」、「維度代碼」和「維度名稱」欄。 displayNameEnabled=false 表示即使在實例的「啟用顯示名稱」設定為開啟時,API 也應繼續遵循 v30 之前的 API 合約。 displayNameEnabled 的預設值為「False」。 | false |
applyValidationRules
僅適用於 API v38 +。 | 否 | applyValidationRules=true 表示當 API 版本大於等於 v38 時,API 將對所有匯入的資料執行模型工作表規則驗證。
applyValidationRules=false 表示 API 將忽略所有匯入資料的模型工作表規則驗證。 ApplyValidationRules 的預設值為「true」。 | false |
元素內容
| |||
(無) | |||
版本元素
| |||
標記名稱
| 版本 | ||
說明
| 指出應使用哪個版本來接收要求的資料。必須為每個呼叫提供版本。 | ||
元素的屬性
| |||
屬性內容名稱
| EOI?
| 值
| 範例
|
名稱 | 否 | 用來接收資料的版本名稱。在單一 API 呼叫中只能存取一個版本。如果未提供名稱,則isDefault 標幟必須設為在此元素上為 True。 | 2014 年度預算 |
isDefault | 否 | 如果呼叫者無論實例名稱為何都希望存取實例的目前預設版本,可將此屬性內容設為 True,在這種情況下,會忽略標記的名稱屬性內容 (如果有)。否則,如果此值為 False 或此屬性內容不存在,則必須存在具有所提供名稱的版本,且使用者可存取此版本才能成功執行此呼叫。 | false |
元素內容
| |||
(無) | |||
工作表元素
| |||
標記名稱
| 工作表 | ||
說明
| 指出應由哪個工作表接收匯入的資料。每個 API 呼叫只能針對一個工作表的資料。 | ||
元素的屬性
| |||
屬性內容名稱
| EOI?
| 值
| 範例
|
名稱 | 是 | 要匯入資料的工作表名稱。 | 人員 |
isUserAssigned | 否 | 表示工作表是按使用者指派的工作表。如果未指定,則預設為 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="modeled-import-success">Personnel import successful. Rows imported: 1</message> <message key="modeled-import-replace">All existing rows were replaced.</message> </messages> </response>
失敗 (使用環境定義)
<?xml version='1.0' encoding='UTF-8'?> <response success="false"> <messages> <message key="modeled-import-failed">The Personnel import has failed.</message> <message key="error-import">Import Failed with the following error: 1 Error(s) Occurred.</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 Plan do not exist: Development1.</message> <message key="invalid-plan-choice-withCoordinate"> <context> <col header="Plan" value="Development1" /> <col header="Region" value="C-US" /> <col header="Title" value="CEO" /> <col header="JobCode" value="E1" /> <col header="Benefits" value="Yes" /> <col header="per" value="Yr" /> <col header="Last Name" value="Topdog" /> <col header="First Name" value="Andy" /> <col header="ID" value="1000" /> <col header="Start" value="12/20/2013" /> <col header="End" value="12/30/2014" /> <col header="Hr/Week" value="80.0" /> <col header="Pay Rate" value="500000.12" /> <col header="Pay Rate Display Column" value="888,888" /> </context> Invalid Level Choice: Development1 on row 1 column A </message> </messages> </response>
失敗 (無環境定義)
<?xml version='1.0' encoding='UTF-8'?> <response success="false"> <messages> <message key="modeled-import-failed">The Personnel import has failed.</message> <message key="error-import">Import Failed with the following error: 1 Error(s) Occurred.</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 Plan do not exist: Development1.</message> <message key="invalid-plan-choice-withCoordinate">Invalid Level Choice: Development1 on row 1 column A</message> </messages> </response>
回應元素
| |||
標記名稱
| 回應 | ||
元素的屬性
| |||
屬性內容名稱
| EOI?
| 值
| 範例
|
成功 | 是 | 兩者之一True 或false,表示 API 呼叫是否成功。即使是成功的呼叫,其回應中也可能包含警告訊息。 | True |
元素內容
| |||
單項選填messages 元素 | |||
訊息元素
| |||
標記名稱
| 訊息 | ||
說明
| 一或多個容器訊息元素 | ||
元素的屬性
| |||
(無) | |||
元素內容
| |||
一項或多項訊息元素 | |||
訊息元素
| |||
標記名稱
| 訊息 | ||
說明
| 表示系統正在將訊息傳回呼叫者。「訊息」用於顯示要求未成功時的錯誤訊息、要求成功時的警告訊息,以及成功時的確認訊息。 | ||
元素的屬性
| |||
屬性內容名稱
| EOI?
| 值
| 範例
|
索引鍵 | 否 | 指定時,金鑰是識別特定訊息或訊息類型的一種方式,可用於用戶端程式中的自動化錯誤記錄和復原。即使訊息的語言變更,關鍵字在要求的不同地區設定下也不會變更。未來也不太可能因為措辭調整或術語變更而變更索引鍵。 | invalid-attributevalueid |
元素內容
| |||
| |||
環境定義元素
| |||
標記名稱
| context | ||
說明
| 一或多個col元素的容器。 | ||
元素的屬性
| |||
屬性內容名稱
| EOI?
| 值
| 範例
|
無 | |||
元素內容
| |||
一或多個col元素 | |||
col 元素
| |||
標記名稱
| 欄 | ||
說明
| 表示訊息的環境定義。提供標頭/值對,以便識別產生訊息的列。 | ||
元素的屬性
| |||
屬性內容名稱
| EOI?
| 值
| 範例
|
標頭 | 是 | 欄的標頭。 | 「帳戶」 |
值 | 是 | 欄中的值。 | "GL-29482-38233" |
元素內容
| |||
(無) | |||