跳至主要内容
Adaptive Planning
上次更新时间 :2024-09-20
importConfigurableModelData

importConfigurableModelData

已在 API v40(2024 年 9 月 21 日)中更新。
种类
数据提交
描述
在模型化工作表中插入、替换或更新数据。
调用所需的权限
导入
请求时需要的参数
Credentials、ImportDataOptions、Version、Sheet、RowData
此方法的请求包含参数,这些参数将用于确定哪个工作表和哪个版本将接收所提供的数据行。
此方法可以:
  • 将新行附加到工作表。
  • 将模型化工作表上当前的所有行替换为导入内容。
  • 仅为导入的层级替换工作表中的所有数据
  • 通过将导入中的行与导入键进行匹配来更新现有行。
  • 通过将导入中的行与导入键进行匹配来更新现有行,并添加新行。
此 API 的每次调用都必须恰好包含以下每种列出类型的一个元素:
  • credentials
  • 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 调用都必须包含一个凭据元素,用于识别调用 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
否
仅当要导入的数据每行具有一组时间跨度时使用。如果moveBPtr 设置为如果为 true,则导入操作会将实际值版本中的实际值可用性指针移至导入数据中找到的最新时段。如果设置为如果为 false,则导入操作不会影响任何版本上显示实际值的时段。如果 planOrActuals 设置为“计划”,则必须将此属性设置为“false”。
否
allowParallel
是
如果设置为true,则即使此实例已存在另一个正在进行的实际值或交易导入,导入也会继续进行。如果设置为如果此实例已存在正在处理的实际值或交易导入,则将其设置为 false,则导入尝试将失败。
false
useMappings
否
指定是否对行元素内的账户、计划和维度值使用导入映射。已考虑默认为 true。如果如果为 false,则应使用内部编号:账户按代码标识,层级按名称标识,维度值按名称标识。
false
replaceExisting
否
如果设置为“1”或“true”,则会将所有层级上的所有现有行替换为要导入的新行。 (即清除所有层级上先前存在的所有行)。只有拥有
“导入到所有位置”
权限的用户才能使用此选项。
如果设置为“0”或“false”,则系统会将导入的行附加到现有行(即使新行是重复行)。
如果设置为“2”,则会将模型化工作表中的现有行替换为要导入的新行,但仅限于具有匹配层级和受保护维度的行。如果层级和受保护的维度组合所在的行在上传的电子表格中没有任何未拆分的行,则系统不会移除其现有行,除非该行是通过上传操作替换的行的拆分行。
updateExisting 会检查已使用的维度,以及同一层级、账户、时段和版本中是否存在数据。如果存在行键,系统还会匹配行键列。
如果系统中同一位置存在数据,则导入操作会替换这些数据。此替换会逐行进行。导入操作不会同时替换所有内容。不匹配的导入行会附加到工作表。
例如,您执行了两次导入。但您的第一个导入文件和第二个导入文件所加载的数据不同,则系统将在第二次导入后保留现有数据。
如果要删除特定列中的所有数据,请包括该列,但将其列值留空。未提及的列的列值保持不变。
设置为“3”可更新模型化工作表中的现有行,以反映正在导入的新行。如果任何行与现有行不匹配,系统将返回警告。此模式需要 importKey。选中
“允许拆分”
的工作表不支持更新。
如果设置为“4”,则会更新模型化工作表中的现有行,以反映正在导入的新行,并为与现有行不匹配的任何行插入新行。此模式需要 importKey。只有“导入键”列、“层级”列和任意文本选择器列为必填列,即使不添加新行也是如此。选中
“允许拆分”
的工作表不支持更新。
如果设置为 5,则系统会根据当前仅支持“仅按层级替换”功能的输入层级的范围替换现有行。该范围是使用新的范围元素提供的。在导入中,负载只会替换与给定范围匹配的行。与范围不匹配的行将不受影响。
默认值为 true。
True
importKey
否
更新模型化工作表行时用作导入键的模型化工作表列名称。
Adaptive Planning
使用导入键列将导入中的每一行与模型化工作表中的行进行匹配。每行的导入键值必须唯一。
仅当replaceExisting 为“3”或“4”时,才能使用此属性。
导入键列可以是以下列之一:
  • 层级列
  • 维度列
Level
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
元素的内容
(无)
版本元素
标记名称
版本
描述
指示应使用哪个版本来接收所请求的数据。必须为每次调用提供版本。
元素的属性
属性名称
必填?
值
示例
名称
否
要用于接收数据的版本的名称。在单个 API 调用中只能访问一个版本。如果未提供名称,则isDefault 标志必须设置为在此元素上为 true
2014 年预算
isDefault
否
如果调用方希望访问实例的当前默认版本(无论其名称为何),则可以将此属性设置为 true,在这种情况下,标记的 name 属性(如果存在)将被忽略。否则,如果此值为 false 或此属性不存在,则必须存在具有所提供名称的版本,并且该版本可供用户访问,此调用才能成功。
false
元素的内容
(无)
工作表元素
标记名称
工作表
描述
指明哪个工作表应接收导入的数据。每个 API 调用只能定位一个工作表的数据。
元素的属性
属性名称
必填?
值
示例
名称
是
要导入数据的工作表的名称。
人员
isUserAssigned
否
表明工作表是按用户指定的工作表。如果未指定,则默认为 false,表示它是按层级指定的工作表。
false
元素的内容
(无)
范围元素
标记名称
范围(适用于 API v40)
描述
指定此导入的范围。示例:
<scope> <levels> mode="INPUT"/> </scope>
仅当 importDataOptions 元素的“replaceExisting”属性为“5”时才允许使用此选项。
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="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>
回复元素
标记名称
回复
元素的属性
属性名称
必填?
值
示例
成功
是
两者之一正确或false,指示 API 调用是否成功。即使成功调用,响应中也可能包含警告消息。
是
元素的内容
单个可选messages 元素
messages 元素
标记名称
消息
描述
一个或多个容器消息元素
元素的属性
(无)
元素的内容
一个或多个消息元素
消息元素
标记名称
消息
描述
表示从系统发回给调用方的消息。消息用于在请求未成功时显示错误消息,在请求成功时显示警告消息,在成功时显示确认消息。
元素的属性
属性名称
必填?
值
示例
键
否
指定密钥后,密钥可用于识别特定消息或消息类型,可用于在客户端程序中自动记录错误并进行恢复。在不同的请求区域设置下,即使消息的语言发生变化,键也不会发生变化。关键字在将来也不太可能因措辞调整或术语变更而发生变化。
invalid-attributevalueid
元素的内容
  1. 消息的文本。此文本使用请求中指定的区域设置的语言(假设该区域设置受支持)。文本还可能包含可变信息,例如已处理的行数,或者导致错误的特定列或值。
  2. 可选的上下文元素。
相关信息元素
标记名称
相关信息
描述
一个或多个 col 元素的容器。
元素的属性
属性名称
必填?
值
示例
无
元素的内容
一个或多个 col 元素。
col 元素
标记名称
col
描述
表示消息的上下文。提供一个标头/值对,以便识别生成消息的行。
元素的属性
属性名称
必填?
值
示例
表头
是
列的标题。
“账户”
值
是
列中的值。
"GL-29482-38233"
元素的内容
(无)