跳至主要内容
文档
文档
Adaptive Planning
上次更新时间 ：2024-09-20
importStandardData

importStandardData

在 API v40 中更新（2024 年 9 月 13 日）
种类
数据提交
描述
在标准账户中插入或替换数据。
调用所需的权限
导入到所有位置
清除数据（API v36+ 以支持 REPLACE 模式）
请求时需要的参数
Credentials、ImportDataOptions、Version、RowData
includeDescendants
此方法的请求包含参数，这些参数将用于确定哪个版本将接收所提供的数据行。可以将数据导入到任何标准账户（总分类账账户、自定义账户、假设账户或汇率）中，无论该账户是否已放置在工作表中。
importStandard 数据无法导入到使用
“重设公式设置”
的
“数据输入”
 的账户。

申请格式


<?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 的每次调用都必须恰好包含以下每种列出类型的一个元素：
  • credentials
  • 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 调用都必须包含一个凭据元素，用于识别调用 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 设置为计划
否
allowParallel
是
仅在以下情况下使用planOrActuals 属性设置为实际值如果设置为true，则即使此实例已存在另一个正在进行的实际值或交易导入，导入也会继续进行。如果设置为如果此实例已存在正在处理的实际值或交易导入，则将其设置为 false，则导入尝试将失败。
false
useMappings
否
指定是否对行元素内的账户、计划和维度值使用导入映射。已考虑默认为 true。如果如果为 false，则应使用内部编号：账户按代码标识，层级按名称标识，维度值按名称标识。
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+
否
指定导入模式，可以是“附加”或“替换”。
附加
更新现有事实或添加新事实。系统不会删除任何事实。
替换
该请求必须包含一个表示超多维坐标的 Scope 元素，该元素中的数据将替换为负载中提供的数据。范围内任何现有数据，如果负载中没有匹配的坐标，都将被删除。
此模式属性在 API v36 及更高版本中受支持。使用 mode="REPLACE" 调用早期版本的 API 会出错。
如果未指定，模式的默认值为“附加”。
附加
元素的内容
（无）
版本元素
标记名称
版本
描述
指示应使用哪个版本来接收所请求的数据。必须为每次调用提供版本。
元素的属性
属性名称
必填？
值
示例
名称
否
要用于接收数据的版本的名称。在单个 API 调用中只能访问一个版本。如果未提供名称，则必须将此元素上的 isDefault 标志设置为 true。
要获取经折算的币种版本及其名称的列表，请发出exportVersions 请求，并在 include 元素中添加currencyVersions=true。
2014 年预算
isDefault
否
如果调用方希望访问实例的当前默认版本（无论其名称为何），则可以将此属性设置为 true，在这种情况下，标记的 name 属性（如果存在）将被忽略。否则，如果此值为 false 或此属性不存在，则必须存在具有所提供名称的版本，并且该版本可供用户访问，此调用才能成功。
false
元素的内容
（无）
范围元素
标记名称
范围
仅适用于 API 版本 36+
描述
指定此导入的范围。
仅当 importDataOptions 元素的 mode 属性为 REPLACE 时才允许。
元素的属性
属性名称
必填？
值
示例
EraseCellNotes
否
指定是否清除范围中的单元格注释。必须为以下 3 个枚举值之一：
无
 - 不清除单元格注释。
全部
 - 清除范围内的所有单元格注释。
MODIFIED_ONLY
- 清除范围内因导入操作而修改的单元格的单元格注释。这包括以前为空但导入了事实的单元格，以及事实已被清除的单元格。
如果未指定 EraseCellNotes，则默认为 NONE。
无
元素的内容
一个
时间
 元素、一个
账户
 元素和一个
层级
 元素，所有元素均为必选。
账户元素
标记名称
账户
仅适用于 API 版本 36+
描述
指定导入范围的账户。如果指定的账户存在，但导入数据中没有此账户的数据，则系统会针对时间范围和范围坐标的其余部分移除此账户中的数据。
仅当 importDataOptions 元素的 mode 属性为 REPLACE 时才允许。
元素的属性
属性名称
必填？
值
示例
模式
是
指定账户范围的模式。必须为以下三个选项之一。
EXPLICIT
- 如果指定了此模式，则预期会看到一个或多个用于确定导入账户范围的账户子元素。
INPUT
- 如果指定此模式，账户范围将由导入数据中存在的唯一账户集确定。
注意：标准导入范围不允许账户模式为“ALL”。
显式
元素的内容
如果 mode 为
INPUT
，则不能有任何 <account> 子元素。
如果模式为
“EXPLICIT”
，则必须有一个或多个 <account> 子元素。
如果模式为
EXPLICIT
，并且 <account> 子元素中的任何账户代码无效，则整个 <accounts> 元素（也可能包括 <Scope>）都将被视为无效。对于每个无效代码，系统将在响应中包含一条错误消息。
账户元素
标记名称
account
仅适用于 API 版本 36+
描述
指定要包括在导入范围内的账户代码。
仅当 importDataOptions 元素的 mode 属性为 REPLACE 时才允许。
元素的属性
属性名称
必填？
值
示例
includeDescendants
否
如果账户是叶账户，则 includeDescendants 无效。
如果该账户是父级账户，则将此属性指定为 true 将在范围内包括此账户的所有叶后代。
如果该账户是父级账户并且 includeDescendants 为 false，则会出错。我们只能导入到叶账户。
这是可选属性，默认值为 false。
是
选择器
否
指定账户元素内容类型：
  • 代码账户元素内容是账户代码。示例：
    <account selector="code">30440</account>
    在此示例中，30440 是账户代码。
  • 类型账户元素内容是一种账户类型。示例：
    <account selector="type">GL</account>
    在此示例中，账户元素类型为所有总分类账账户。目前，标准导入的账户类型仅支持“总分类账”和“自定义”。所有其他内容都会导致错误。
选择器的默认值为 code。
元素的内容
用作导入范围一部分的账户的账户代码，区分大小写。例如，“应付账款”。此代码不得为空，并且与此代码对应的账户必须存在。该账户不能是系统账户或源关联账户。如果账户是计算型账户，则必须有适用于该账户的数据输入重设，否则该账户将被视为无效。
如果账户代码无效，则整个 <accounts> 元素（进而包括 <Scope>）都将被视为无效。
层级元素
标记名称
层级
仅适用于 API 版本 36+
描述
指定导入范围的层级代码。如果在此处指定了层级代码，但导入数据中没有此层级的数据，则系统会针对该时间范围和其余的范围坐标移除此层级中的数据。
仅当 importDataOptions 元素的 mode 属性为 REPLACE 时才允许。
元素的属性
属性名称
必填？
值
示例
模式
是
指定层级范围的模式。必须为以下三个选项之一。
EXPLICIT
- 如果指定此模式，我们预计会看到一个或多个 <level> 子元素，这些子元素将确定导入的层级范围。
INPUT
- 如果指定此模式，层级范围将由导入数据中存在的唯一层级集确定。
ALL
- 如果指定此模式，则层级范围将为所有可导入的层级。
显式
元素的内容
如果模式为“INPUT”或“ALL”，则不能有任何 <level> 子元素。
如果模式为“EXPLICIT”，则必须有一个或多个 <level> 子元素。
如果模式为“EXPLICIT”，并且 <level> 子元素中的任何层级代码无效，则整个 <levels> 元素（也可能包括 <Scope>）都将被视为无效。对于每个无效代码，系统将在响应中包含一条错误消息。
层级元素
标记名称
level
仅适用于 API 版本 36+
描述
指定要包括在导入范围中的层级代码。
仅当 importDataOptions 元素的 mode 属性为 REPLACE 时才允许。
元素的属性
属性名称
必填？
值
示例
includeDescendants
否
如果层级是父级层级，则将此属性指定为 true 将包括此层级的所有叶后代，包括范围中的自身（“Only”节点）。
这是可选属性。
如果未提供此属性，则默认值为 false。如果未提供该属性或将该属性设置为 false，并且指定的层级是父级，则表示导入操作将考虑该层级的“仅限工程”节点作为范围。除非其他层级元素明确指定，否则该层级的子级不会包含在范围内。
是
元素的内容
指定层级代码（区分大小写）。例如，<level>发展阶段</level>。
如果层级代码存在问题（例如未找到代码的层级），则整个 <levels> 以及可能的 <Scope> 都将被视为无效。对于每个无效代码，系统将在响应中包含一条错误消息。
时间元素
标记名称
time
仅适用于 API 版本 36+
描述
指定一个或多个表示导入时间范围的时间范围。
仅当 importDataOptions 元素的 mode 属性为 REPLACE 时才允许。
元素的属性
属性名称
必填？
值
示例
模式
是
指定时间范围的模式。应为以下三个选项之一。
INPUT
- 如果指定此模式，则时间范围将由中的时间代码确定。
<header>
 元素。如果标头包含两个月，则导入范围将为这两个月。
EXPLICIT
- 如果指定了此模式，则系统预期会显示一个或多个用于确定导入时间范围的 timeRange 子元素。
VERSION
- 如果指定此模式，时间范围将为版本的开始时间和结束时间，包括任何初始余额期间。
如果模式为“INPUT”或“VERSION”，则不允许有任何 timeRange 子元素。如果存在 timeRange 子元素，则系统会将其视为错误。
输入
元素的内容
一个或多个 timeRange 元素，除非模式为 INPUT 或 VERSION。
timeRange 元素
标记名称
timeRange
仅适用于 API 版本 36+
描述
为时间范围指定单个时间范围。
仅当 importDataOptions 元素的 mode 属性为 REPLACE 时才允许。
元素的属性
属性名称
必填？
值
示例
开始
是
导入时间范围的开始期间。
07/2021
结束
是
导入时间范围的结束期间。
08/2021
元素的内容
一个或多个 timeRange 元素，除非模式为 INPUT 或 VERSION。
rowData 元素
标记名称
rowData
描述
正在导入的数据行的容器。
元素的属性
（无）
元素的内容
刚好 1标头元素，并且恰好是一个rows 元素。
表头元素
标记名称
表头
描述
指定相应数据源中数据列的名称和顺序。rows 元素。
元素的属性
（无）
元素的内容
一行文本，列名称之间用竖线分隔。这些列名称必须与工作表上的维度或字段名称相对应，或者与可包含数据的时段代码相对应。列名称与要导入数据的工作表的导入模板中的列名称相同，每个列标题与下一个列标题之间用竖线符号或管道符号分隔。
对于启用了“显示名称”的实例，标头不支持
"<dimension>"
 与
"<dimension> Name"
 或
"<dimension> Code"
 在 Adaptive Planning 支持的区域设置中使用 API v30 或更高版本。
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>
回复元素
标记名称
回复
元素的属性
属性名称
必填？
值
示例
成功
是
两者之一正确或false，指示 API 调用是否成功。即使成功调用，响应中也可能包含警告消息。
是
元素的内容
单个可选messages 元素
messages 元素
标记名称
消息
描述
一个或多个容器消息元素
元素的属性
（无）
元素的内容
一个或多个消息元素
消息元素
标记名称
消息
描述
表示从系统发回给调用方的消息。消息用于在请求未成功时显示错误消息，在请求成功时显示警告消息，在成功时显示确认消息。
元素的属性
属性名称
必填？
值
示例
键
否
指定密钥后，密钥可用于识别特定消息或消息类型，可用于在客户端程序中自动记录错误并进行恢复。在不同的请求区域设置下，即使消息的语言发生变化，键也不会发生变化。关键字在将来也不太可能因措辞调整或术语变更而发生变化。
invalid-attributevalueid
元素的内容
  1. 消息的文本。此文本使用请求中指定的区域设置的语言（假设该区域设置受支持）。文本还可能包含可变信息，例如已处理的行数，或者导致错误的特定列或值。
  2. 可选的上下文元素。
相关信息元素
标记名称
相关信息
描述
一个或多个 col 元素的容器。
元素的属性
属性名称
必填？
值
示例
无
元素的内容
一个或多个 col 元素。
col 元素
标记名称
col
描述
表示消息的上下文。提供一个标头/值对，以便识别生成消息的行。
元素的属性
属性名称
必填？
值
示例
表头
是
列的标题。
“账户”
值
是
列中的值。
"GL-29482-38233"
元素的内容
（无）