跳至主要内容
Adaptive Planning
上次更新时间 :2023-06-23
importCubeData

importCubeData

种类
数据提交
描述
在多维工作表中插入或替换数据。通过将零导入到多维工作表中的各个位置,此方法还可用于从多维工作表中删除数据。将零导入到多维工作表时会清除零所在位置的数据。
调用所需的权限
导入
请求时需要的参数
Credentials、ImportDataOptions、Version、Sheet、RowData
此方法的请求包含参数,这些参数将用于确定哪个工作表和哪个版本将接收所提供的数据行。通过将零导入到多维工作表中的各个位置,此方法还可用于从多维工作表中删除数据。将零导入到多维工作表时会清除零所在位置的数据。

申请格式

<?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
此外,如果将模式指定为 REPLACE,则必须指定范围元素。
对于 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>
凭据元素
标记名称
凭据
描述
所有 API 调用都必须包含一个凭据元素,用于识别调用 API 的用户。然后,系统会以此用户身份执行 API 调用(系统中的任何审核线索或操作历史记录都将显示此用户执行了该操作),因此,用户必须具有执行该操作所需的权限,才能执行 API 调用。成功。
元素的属性
属性名称
必填?
示例
登录
调用 API 方法的用户的登录名。此用户必须具有所需的权限才能调用该方法。
sampleuser@company.com
密码
调用 API 方法的用户的密码。
my_password
区域设置
指定用于解释传入数字和日期的区域设置,以及用于设置传出数字和日期格式的区域设置(使用正确的千位分隔符,时段名称和日期格式)。区域设置还用于指定回复中的任何系统消息应使用的语言。如果未指定,则使用 en_US(美式英语)。
fr_FR
instanceCode
如果凭据中指定的用户有权访问多个 Adaptive Planning 实例,则此属性可用于指明该用户打算访问默认实例以外的实例。如果未指定,则将使用用户的默认实例。要确定可用的实例代码,请使用 exportInstances API。
MYINSTANCE1
元素的内容
(无)
importDataOptions element
标记名称
importDataOptions
描述
指定执行导入时要使用的选项。
元素的属性
属性名称
必填?
示例
planOrActuals
设置为以下选项之一:计划”或“实际值”来指定要导入的数据类型。如果此设置与中指定的版本冲突,版本标记版本标记的值优先,系统会忽略此设置。
计划
moveBPtr
仅在以下情况下使用planOrActuals 属性设置为实际值如果moveBPtr 设置为如果为 true,则导入操作会将实际值版本中的实际值可用性指针移至导入数据中找到的最新时段。如果设置为如果为 false,则导入操作不会影响任何版本上显示实际值的时段。在以下情况下,必须将此属性设置为 false:planOrActuals 设置为计划
false
allowParallel
仅在以下情况下使用planOrActuals 属性设置为实际值如果设置为true,则即使此实例已存在另一个正在进行的实际值或交易导入,导入也会继续进行。如果设置为如果此实例已存在正在处理的实际值或交易导入,则将其设置为 false,则导入尝试将失败。
false
useMappings
指定是否对行元素内的账户、计划和维度值使用导入映射。已考虑默认为 true。如果如果为 false,则应使用内部编号:账户按代码标识,层级按名称标识,维度值按名称标识。
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+
指定导入模式,可以是“附加”或“替换”之一。
附加 - 更新现有事实或插入新事实。系统不会删除任何事实。
REPLACE – 调用方必须指定表示多维工作表坐标的范围元素,多维工作表中的数据将替换为负载中提供的数据。该范围内的所有现有数据都将替换为调用负载中的数据。
自 API v32 及更高版本起支持此选项。使用早期版本调用 API 将导致错误。
如果未指定,模式的默认值为“附加”。
替换
元素的内容
(无)
版本元素
标记名称
版本
描述
指示应使用哪个版本来接收所请求的数据。必须为每次调用提供版本。
元素的属性
属性名称
必填?
示例
名称
要用于接收数据的版本的名称。在单个 API 调用中只能访问一个版本。如果未提供名称,则isDefault 标志必须设置为在此元素上为 true
2012 年预算
isDefault
如果调用方希望访问实例的当前默认版本(无论其名称为何),则可以将此属性设置为 true,在这种情况下,标记的 name 属性(如果存在)将被忽略。否则,如果此值为 false 或此属性不存在,则必须存在具有所提供名称的版本,并且该版本可供用户访问,此调用才能成功。
false
元素的内容
(无)
工作表元素
标记名称
工作表
描述
指明哪个工作表应接收导入的数据。每个 API 调用只能定位一个工作表的数据。
元素的属性
属性名称
必填?
示例
名称
要导入数据的工作表的名称。
人员
isUserAssigned
表明工作表是按用户指定的工作表。如果未指定,则默认为 false,表示它是按层级指定的工作表。
false
元素的内容
(无)
范围元素
标记名称
范围
描述
指定此导入的范围。仅当将导入模式指定为 REPLACE 时适用。
适用于 API v32+
元素的属性
属性名称
必填?
示例
模式
指定是否清除范围中的单元格注释。必须为以下 3 个枚举值之一:
  • 无 - 不清除单元格注释。
  • 全部 - 清除范围内的所有单元格注释。
  • MODIFIED_ONLY - 清除范围内因导入操作而修改的单元格的单元格注释。这包括以前为空但导入了事实的单元格,以及事实已被清除的单元格。
如果未指定 EraseCellNotes,则默认为 NONE。
元素的内容
一个时间元素、一个账户元素和一个层级元素,所有这些元素均为必选元素。
时间元素
标记名称
Time
描述
指定一个或多个表示导入时间范围的时间范围。
适用于 API v32+
元素的属性
属性名称
必填?
示例
模式
指定时间范围的模式。应为以下三个选项之一:
  • INPUT - 如果指定此模式,时间范围将由 <header> 元素中的时间代码确定。如果标头包含两个月,则导入范围将为这两个月。
  • EXPLICIT - 如果指定了此模式,则系统预期会显示一个或多个用于确定导入时间范围的 timeRange 子元素。
  • VERSION - 如果指定此模式,时间范围将为版本的开始时间和结束时间,包括任何初始余额期间。
如果已指定模式,并且模式为“INPUT”或“VERSION”,则不应包括任何 timeRange 元素。如果存在,则将被视为错误条件。
指定 VERSION 时会将版本开始日期考虑在内,即使计划开始日期晚于版本开始日期也是如此。
输入
元素的内容
一个或多个 timeRange 元素,除非模式为 INPUT 或 VERSION。
timeRange 元素
标记名称
TimeRange
描述
为时间范围指定单个时间范围。
适用于 API v32+
元素的属性
属性名称
必填?
示例
开始
导入时间范围的开始期间。
07/2021
结束
导入时间范围的结束期间。
08/2021
元素的内容
(无)
账户元素
标记名称
账户
描述
指定导入范围的账户代码。如果此处存在账户代码,但在导入数据中没有此账户的数据,则系统会针对该时间范围和其余的范围坐标移除此账户中的数据。
适用于 API v32+
元素的属性
属性名称
必填?
示例
模式
指定账户范围的模式。必须是以下三个选项之一:
  • EXPLICIT - 如果指定了此模式,则预期会看到一个或多个用于确定导入账户范围的账户子元素。
  • INPUT - 如果指定此模式,账户范围将由导入数据中存在的唯一账户集确定。
  • 全部 - 如果指定此模式,账户范围将为要导入的所有账户。对于多维工作表导入,这将表示该多维工作表的所有可导入账户。
如果模式已指定且为“INPUT”或“ALL”,则不应包括任何账户子元素。如果存在,则将被视为错误条件。
显式
元素的内容
一个或多个账户元素,除非模式为“INPUT”或“ALL”。
账户元素
标记名称
account
描述
指定要包括在导入范围内的账户代码。
适用于 API v32+
元素的属性
属性名称
必填?
示例
includeDescendants
如果账户是叶账户,则 includeDescendants 无效。
如果该账户是父级账户,则将此属性指定为 true 将在范围内包括此账户的所有叶后代。
如果账户是父级账户,并且 includeDescendants 为假,则系统将视为未指定此账户元素。
如此处理父级账户的原因是,叶账户有时可能会被提升为父级账户,而导入规范可能无法及时更新以反映此变更。使用 includeDescendants=false 忽略父级账户可防止意外删除数据。
这是可选属性,默认值为 false。
True
元素的内容
指定用作导入范围一部分的账户的账户代码。例如,Operational_Expense。
层级元素
标记名称
层级
描述
指定导入范围的层级代码。如果在此处指定了层级代码,但导入数据中没有此层级的数据,则系统会针对该时间范围和其余的范围坐标移除此层级中的数据。
适用于 API v32+
元素的属性
属性名称
必填?
示例
模式
指定层级范围的模式。必须是以下三个选项之一:
  • EXPLICIT - 如果指定了此模式,则系统会看到一个或多个层级子元素,这些子元素将确定导入的层级范围。
  • INPUT - 如果指定此模式,层级范围将由导入数据中存在的唯一层级集确定。
  • ALL - 如果指定此模式,则层级范围将为所有可导入的层级。
如果模式已指定且为“INPUT”或“ALL”,则不应包括任何层级子元素。如果存在,则将被视为错误条件。
输入
元素的内容
一个或多个层级元素,除非将模式指定为“INPUT”或“ALL”。
层级元素
标记名称
level
描述
指定要包括在导入范围中的层级代码。
适用于 API v32+
元素的属性
属性名称
必填?
示例
includeDescendants
如果层级是父级层级,则将此属性指定为 true 会在范围中包括此层级的所有叶后代,包括自身(“Only”节点)。
这是可选属性。
如果未提供此属性,则默认值为 false。如果未提供该属性或将该属性设置为 false,并且指定的层级是父级,则表示导入操作将将该层级的“单独”(示例中的“仅限工程”)节点用作范围。除非使用其他层级元素明确指定,否则不会将层级的子级纳入范围。
True
元素的内容
指定作为导入范围一部分的层级的层级代码。例如,“发展”。
rowData element
标记名称
rowData
描述
正在导入的数据行的容器。
元素的属性
(无)
元素的内容
刚好 1标头元素,并且恰好是一个rows 元素。
表头元素
标记名称
表头
描述
指定相应数据源中数据列的名称和顺序。rows 元素。
元素的属性
(无)
元素的内容
一行文本,列名称之间用竖线分隔。这些列名称必须与工作表上的维度或字段名称相对应,或者与可包含数据的时段代码相对应。列名称与要导入数据的工作表的导入模板中的列名称相同,每个列标题与下一个列标题之间用竖线符号或管道符号分隔。
对于启用了“显示名称”的实例,标头不支持
"<dimension>"
"<dimension> Name"
"<dimension> Code"
在 Adaptive Planning 支持的区域设置中使用 API v30 或更高版本。
rows 元素
标记名称
描述
一个或多个容器行元素。
元素的属性
(无)
元素的内容
一个或多个行元素。
行元素
标记名称
描述
正在导入的单个行的数据。
元素的属性
(无)
元素的内容
导入单个行中的字段数据,每个字段的值以竖线或管道符号分隔。数据字段的顺序必须与标头元素中的行顺序相同。如果值中的数字使用千位分隔符,则系统会假定这些分隔符是请求凭据中指定的区域设置中使用的逗号分隔符。

回复格式

以下是有关多维数据导入成功和失败的响应示例。

成功示例

<?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>
回复元素
标记名称
回复
元素的属性
属性名称
必填?
示例
成功
两者之一正确或false,指示 API 调用是否成功。即使成功调用,响应中也可能包含警告消息。
元素的内容
单个可选messages 元素
messages 元素
标记名称
消息
描述
一个或多个容器消息元素。
元素的属性
(无)
元素的内容
一个或多个消息元素。
消息元素
标记名称
消息
描述
表示从系统发回给调用方的消息。消息用于在请求未成功时显示错误消息,在请求成功时显示警告消息,在成功时显示确认消息。
元素的属性
属性名称
必填?
示例
指定密钥后,密钥可用于识别特定消息或消息类型,可用于在客户端程序中自动记录错误并进行恢复。在不同的请求区域设置下,即使消息的语言发生变化,键也不会发生变化。关键字在将来也不太可能因措辞调整或术语变更而发生变化。
invalid-attributevalueid
元素的内容
  • 消息的文本。此文本使用请求中指定的区域设置的语言(假设该区域设置受支持)。文本还可能包含可变信息,例如已处理的行数,或者导致错误的特定列或值。
  • 可选的上下文元素。
相关信息元素
标记名称
context
描述
一个或多个 col 元素的容器。
元素的属性
属性名称
必填?
示例
元素的内容
一个或多个 col 元素。
col 元素
标记名称
描述
表示消息的上下文。提供一个标头/值对,以便识别生成消息的行。
元素的属性
属性名称
必填?
示例
表头
列的标题。
“账户”
列中的值。
“GL-29482-38233”
元素的内容
(无)