importCubeData
種類
| 資料提交 |
說明
| 在 Cube 工作表中插入或取代資料。此方法也可用於將零匯入 Cube 中的位置,以從 Cube 工作表中刪除資料。將零匯入 Cube 工作表會清除零位置的資料。 |
調用所需權限
| 匯入 |
要求時必填參數
| 憑證、ImportDataOptions、Version、工作表、RowData |
此方法的要求包含的參數將用來決定哪個工作表和版本將接收提供的資料列。此方法也可用於將零匯入 Cube 中的位置,以從 Cube 工作表中刪除資料。將零匯入 Cube 工作表會清除零位置的資料。
要求格式
<?xml version='1.0' encoding='UTF-8'?> <call method="importCubeData" 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"/> <version name="Budget 2014" isDefault="false" /> <sheet name="Sales Cube" isUserAssigned="false" /> <rowData> <header>ProductFurniture|CountryRegion|FabricationMachine|Customer|Account|Level|06/2014|07/2014|08/2014|09/2014|01/2015</header> <rows> <row>Coffee table|Argentina|Do-All 15 Vertical|Aeropostale|Price|Corporate Plan|0|0|0|0|0</row> </rows> </rowData> </call>
此 API 呼叫的每次呼叫都必須包含下列每種類型中的一個元素︰
- 憑證
- importDataOptions
- 版本
- 工作表
- rowData
此外,當模式指定為「取代」時,必須指定範圍元素。
如果標頭中的豎線字元 ( | ) 數與資料不符,將會導致 API v30 或更高版本發生錯誤。
指定取代模式和範圍的範例要求︰
<?xml version='1.0' encoding='UTF-8'?> <call method="importCubeData" callerName="a string that identifies your client application"> <credentials login="sampleuser@company.com" password="my_pwd" instanceCode="INSTANCE1"/> <version name="Budget 2022" isDefault="true" /> <sheet name="Expense Cube" isUserAssigned="false" /> <importDataOptions planOrActuals="Plan" allowParallel="false" moveBPtr="false" mode="REPLACE" /> <!-- Scope parameter specifying the import scope.--> <scope> <!-- Specifies the time scope for import. All values will be specified as time codes.--> <time mode="EXPLICIT"> <timeRange start="01/2021" end="10/2021" /> </time> <!-- Specifies list of accounts in the scope. All values will be specified as code field.--> <accounts mode="EXPLICIT"> <account includeDescendants="true">Op_Expense_Inputs</account> <account includeDescendants="true">Op_Expense_Drivers</account> </accounts> <!-- Specifies list of levels in the scope. All values will be specified as code field.--> <levels mode="INPUT"/> </scope> <rowData> <header>ProductFurniture|CountryRegion|FabricationMachine|Customer|Account|Level|01/2022|02/2022|03/2022|04/2022|05/2022|06/2022|07/2022|08/2022|09/2022|10/2022|11/2022|12/2022</header> <rows> <row>Coffee Table|Argentina|Do-All 15 Vertical|Aeropostale|Units|Development|44567.33|21345.77|22341.43|65567.32|298145.12|12641.83|77821.53|7766342.09|211441.21|88712.43|61940.41|662341.03|775420.25|800345.17</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 表示 importCubeData 應有 Account Code , Level Code , Dimension Code , 和 Dimension Name Column 於實例的「啟用顯示名稱」設為開啟時,載入於承載資料中。displayNameEnabled=false 表示即使在實例的「啟用顯示名稱」設為開啟時,importCubeData API 仍應繼續遵循 v30 之前的 API 協定。importCubeData API 會忽略顯示名稱屬性 Account Code , Level Code , Dimension Code , 和 Dimension Name Column 。displayNameEnabled 的預設值為「False」。 | false |
模式
適用於 API v32+ | 否 | 指定匯入模式,為「附加」或「取代」其中之一。
附加 - 更新現有事實或插入新事實。不會刪除任何事實。 取代 - 呼叫者必須指定表示 Cube 座標的範圍元素,在該座標中,資料將取代為承載資料中提供的資料。範圍內的所有現有資料都將取代為呼叫承載資料中的資料。 API v32 及以上版本支援此選項。使用先前版本呼叫 API 會導致錯誤。 未指定時,模式的預設值為 APPEND。 | 取代 |
元素內容 | |||
(無) | |||
版本元素
| |||
標記名稱
| 版本 | ||
說明
| 指出應使用哪個版本來接收要求的資料。必須為每個呼叫提供版本。 | ||
元素的屬性
| |||
屬性內容名稱
| EOI?
| 值
| 範例
|
名稱 | 否 | 用來接收資料的版本名稱。在單一 API 呼叫中只能存取一個版本。如果未提供名稱,則isDefault 標幟必須設為在此元素上為 True。 | 2012 年度預算 |
isDefault | 否 | 如果呼叫者無論實例名稱為何都希望存取實例的目前預設版本,可將此屬性內容設為 True,在這種情況下,會忽略標記的名稱屬性內容 (如果有)。否則,如果此值為 False 或此屬性內容不存在,則必須存在具有所提供名稱的版本,且使用者可存取此版本才能成功執行此呼叫。 | false |
元素內容
| |||
(無) | |||
工作表元素
| |||
標記名稱
| 工作表 | ||
說明
| 指出應由哪個工作表接收匯入的資料。每個 API 呼叫只能針對一個工作表的資料。 | ||
元素的屬性
| |||
屬性內容名稱
| EOI?
| 值
| 範例
|
名稱 | 是 | 要匯入資料的工作表名稱。 | 人員 |
isUserAssigned | 否 | 表示工作表是按使用者指派的工作表。如果未指定,則預設為 False,表示這是按層級指派的工作表。 | false |
元素內容
| |||
(無) | |||
範圍元素
| |||
標記名稱
| 範圍 | ||
說明
| 指定此匯入的範圍。僅適用於將匯入模式指定為「取代」時。
適用於 API v32+ | ||
元素的屬性
| |||
屬性內容名稱
| EOI?
| 值
| 範例
|
模式 | 是 | 指定是否要清除範圍中的儲存格附註。必須是 3 個列舉值之一︰
如果未指定 eraseCellNotes,則預設為「無」。 | 無 |
元素內容
| |||
1 個時間元素、一個科目元素和一個層級元素,這些元素均為必填元素。 | |||
時間元素
| |||
標記名稱
| Time | ||
說明
| 指定一或多個時間範圍,以表示匯入的時間範圍。
適用於 API v32+ | ||
元素的屬性
| |||
屬性內容名稱
| EOI?
| 值
| 範例
|
模式 | 是 | 指定時間範圍的模式。應為下列三個選項之一︰
如果已指定模式且模式為 INPUT 或 VERSION,則不應包含任何 timeRange 元素。如果有,則會被視為錯誤條件。
即使計畫開始日期晚於版本開始日期,指定 VERSION 也會將版本開始日期納入考量。 | 輸入 |
元素內容
| |||
一或多個 timeRange 元素,除非模式為 INPUT 或 VERSION。 | |||
timeRange 元素
| |||
標記名稱
| 時間範圍 | ||
說明
| 指定時間範圍的單一時間範圍。
適用於 API v32+ | ||
元素的屬性
| |||
屬性內容名稱
| EOI?
| 值
| 範例
|
開始 | 是 | 匯入時間範圍的開始期間。 | 07/2021 |
結束 | 是 | 匯入時間範圍的結束期間。 | 08/2021 |
元素內容
| |||
(無) | |||
科目元素
| |||
標記名稱
| 科目 | ||
說明
| 指定匯入範圍的科目代碼。如果此處有科目代碼,但匯入資料中沒有此科目的資料,則會移除此科目中該時間範圍和其餘範圍座標的資料。
適用於 API v32+ | ||
元素的屬性
| |||
屬性內容名稱
| EOI?
| 值
| 範例
|
模式 | 是 | 指定科目範圍的模式。必須是下列三個選項之一︰
如果已指定模式且模式為「輸入」或「全部」,則不應包含任何科目子元素。如果存在,則會被視為錯誤條件。 | 顯式 |
元素內容
| |||
一或多個科目元素,除非模式為「輸入」或「全部」。 | |||
科目元素
| |||
標記名稱
| 科目 | ||
說明
| 指定要包含在匯入範圍中的科目代碼。
適用於 API v32+ | ||
元素的屬性
| |||
屬性內容名稱
| EOI?
| 值
| 範例
|
includeDescendants | 否 | 如果科目是分葉科目,則 includeDescendants 無效。
如果科目是父系科目,則將此屬性內容指定為 True,將會在範圍內包含此科目的所有分葉後代。 如果科目是父系科目且 includeDescendants 為 False,則會將此科目元素視為未指定。 如此處理父系科目的基本原理是,分葉科目有時可能會升級為父系科目,且匯入規範可能無法及時更新以反映此變更。忽略具有 includeDescendants=false 的父系科目可防止意外刪除資料。 這是選填屬性內容,預設值將被視為 False。 | true |
元素內容
| |||
指定做為匯入範圍一部分的科目的科目代碼。例如,Operational_Expense。 | |||
層級元素
| |||
標記名稱
| 層級 | ||
說明
| 指定匯入範圍的層級代碼。如果在此指定了層級代碼,但匯入資料中沒有此層級的資料,則會移除此層級中該時間範圍和其餘範圍座標的資料。
適用於 API v32+ | ||
元素的屬性
| |||
屬性內容名稱
| EOI?
| 值
| 範例
|
模式 | 是 | 指定層級範圍的模式。必須是下列三個選項之一︰
如果已指定模式且模式為「輸入」或「全部」,則不應包含任何層級子元素。如果存在,則會被視為錯誤條件。 | 輸入 |
元素內容
| |||
一或多個層級元素,除非模式已指定為 INPUT 或 ALL。 | |||
層級元素
| |||
標記名稱
| 層級 | ||
說明
| 指定要包含在匯入範圍中的層級代碼。
適用於 API v32+ | ||
元素的屬性
| |||
屬性內容名稱
| EOI?
| 值
| 範例
|
includeDescendants | 否 | 如果該層級是父系層級,則將此屬性內容指定為 True,將會在範圍中包含此層級的所有分葉後代,包括其本身 (Only 節點)。
這是選填屬性內容。 如果未提供屬性內容,則預設值為 False。如果未提供屬性內容,或提供為 False,且指定的層級是父系層級,則表示匯入會將該層級的「僅限 (例如「僅限工程」) 節點納入範圍。除非使用其他層級元素明確指定,否則不會將層級的子系視為範圍。 | true |
元素內容
| |||
將層級的層級代碼指定為匯入範圍的一部分。例如,發展。 | |||
rowData element
| |||
標記名稱
| rowData | ||
說明
| 要匯入的資料列的容器。 | ||
元素的屬性
| |||
(無) | |||
元素內容
| |||
正好一個標頭元素且正好一個rows 元素 | |||
標頭元素
| |||
標記名稱
| 標頭 | ||
說明
| 指定對應項目中資料的欄名稱和順序。rows 元素 | ||
元素的屬性
| |||
(無) | |||
元素內容
| |||
具有以豎線分隔欄名稱的一行文字。這些欄名稱必須與工作表上維度或欄位的名稱相對應,或是可包含資料的時段代碼。這些欄位與要匯入資料的工作表的「匯入範本」中的欄名稱相同,且各欄標頭之間以垂直橫條或豎線符號分隔。
對於啟用「顯示名稱」的實例,標頭不支援 "<dimension>" 結合 "<dimension> Name" 或 "<dimension> Code" API v30 或更高版本的 Adaptive Planning 支援的地區設定。 | |||
rows 元素
| |||
標記名稱
| 列 | ||
說明
| 一或多個容器列元素 | ||
元素的屬性
| |||
(無) | |||
元素內容
| |||
一項或多項列元素 | |||
列元素
| |||
標記名稱
| 列 | ||
說明
| 正在匯入的單列資料 | ||
元素的屬性
| |||
(無) | |||
元素內容
| |||
正在匯入的單列中欄位的資料,每個欄位的值以垂直條或豎線符號分隔。資料欄位的順序必須與標頭元素中各行的順序相同。如果值中的數字使用千分位分隔符號,系統會假設這些數字是要求憑證中指定的地區設定中使用的逗號分隔符號。 | |||
回覆格式
以下是 Cube 資料匯入成功和失敗的回應範例。
成功範例
<?xml version='1.0' encoding='UTF-8'?> <response success="true"> <messages> <message key="warning-no-data-imported-dimension-unmapped">Warning: Row 3 was not imported because Coffeee table is unmapped.</message> </messages> </response>
失敗 (使用環境定義)
<?xml version='1.0' encoding='UTF-8'?> <response success="false"> <messages> <message key="err-incomplete-cube-row"> <context> <col header="ProductFurniture" value="Coffee table" /> <col header="CountryRegion" value="" /> <col header="Account" value="Do-All 15 Vertical" /> <col header="Level" value="Aeropostale" /> <col header="06/2014" value="Price" /> <col header="07/2014" value="Corporate Plan" /> <col header="08/2014" value="0.0" /> <col header="09/2014" value="0.0" /> <col header="01/2015" value="0.0" /> </context> Row 1 is missing a value. </message> <message key="err-no-rows">You must import at least one row of data.</message> </messages> </response>
失敗 (無環境定義)
<?xml version='1.0' encoding='UTF-8'?> <response success="false"> <messages> <message key="err-incomplete-cube-row">Row 1 is missing a value.</message> <message key="err-no-rows">You must import at least one row of data.</message> </messages> </response>
回應元素
| |||
標記名稱
| 回應 | ||
元素的屬性
| |||
屬性內容名稱
| EOI?
| 值
| 範例
|
成功 | 是 | 兩者之一True 或false,表示 API 呼叫是否成功。即使是成功的呼叫,其回應中也可能包含警告訊息。 | True |
元素內容
| |||
單項選填messages 元素 | |||
訊息元素
| |||
標記名稱
| 訊息 | ||
說明
| 一或多個容器訊息元素 | ||
元素的屬性
| |||
(無) | |||
元素內容
| |||
一項或多項訊息元素 | |||
訊息元素
| |||
標記名稱
| 訊息 | ||
說明
| 表示系統正在將訊息傳回呼叫者。「訊息」用於顯示要求未成功時的錯誤訊息、要求成功時的警告訊息,以及成功時的確認訊息。 | ||
元素的屬性
| |||
屬性內容名稱
| EOI?
| 值
| 範例
|
索引鍵 | 否 | 指定時,金鑰是識別特定訊息或訊息類型的一種方式,可用於用戶端程式中的自動化錯誤記錄和復原。即使訊息的語言變更,關鍵字在要求的不同地區設定下也不會變更。未來也不太可能因為措辭調整或術語變更而變更索引鍵。 | invalid-attributevalueid |
元素內容
| |||
| |||
環境定義元素
| |||
標記名稱
| context | ||
說明
| 一或多個col元素的容器。 | ||
元素的屬性
| |||
屬性內容名稱
| EOI?
| 值
| 範例
|
無 | |||
元素內容
| |||
一或多個col元素 | |||
col 元素
| |||
標記名稱
| 欄 | ||
說明
| 表示訊息的環境定義。提供標頭/值對,以便識別產生訊息的列。 | ||
元素的屬性
| |||
屬性內容名稱
| EOI?
| 值
| 範例
|
標頭 | 是 | 欄的標頭。 | 「帳戶」 |
值 | 是 | 欄中的值。 | "GL-29482-38233" |
元素內容
| |||
(無) | |||