Versions

URL 端点

支持的 HTTP VERB

GET

请求 URI

/api/rest/modeling/v1/{tenant}/versions： 检索租户的所有版本

以列表的形式检索租户的所有版本。 未在特定版本的用户界面上显示的属性不会包含在响应的相应版本对象中。例如，startOfVersion 表示子实际值版本。 能够通过“limit”和“offset”参数使用分页。 以下版本属性当前在 GET 中不受支持/不显示： 基础版本（适用于虚拟版本）、启用固定汇率报告（适用于虚拟版本）、 计算公式值、管理员访问权限、用户访问权限、可编辑工作表访问权限、特权实际值访问权限、组、组访问级别。

请求 URI 示例：

HTTPS://api.adaptiveplanning.com/api/rest/modeling/v1/DACCO/versions?limit=25&offset=1

请求正文示例：

<留空>

查询参数：

名称	描述	必填
limit	单个响应中的最大对象数。	否
抵销	响应集合中第一个对象的索引（从零开始）。默认值为 0。 将 offset 与 limit 参数结合使用，可控制回复集合的分页。	否

路径参数：

名称	描述	必填
租户	要操作的租户，例如 GREENCO	是

示例回复

200 OK

注：实际值版本的“版本起始值”和计划版本的“左侧滚动限制”均显示在 startOfVersion 属性下（指针 A）。

同样，实际值版本的“版本结束”和计划版本的“计划结束”都显示在 endOfVersion 属性下（指针 D）。

实际值版本的“起始滚动位置”和计划版本的“计划开始”都显示在startingScrollLocation 属性下（指针 C）。

成功响应。

示例回复

{ "data": [ { "name": "Test-Actuals-Version", "shortName": "Test-Actuals-Version-Shortname", "versionType": "ACTUALS", ... "lockLeadingCompletion": true }, { "name": "JE Sub under Actuals", "shortName": "JE01", "parent": "Actuals", ... "journalEntryVersion": true, "journalEntryVersionProperties": { "journalEntryNumbering": "N", "startingNumber": 0 }, ... }, ... ], "limit": 12, "offset": 4, "total": 12 }

DELETE

申请

/api/rest/modeling/v1/{tenant}/versions： 删除现有版本

删除具有指定版本名称的版本。 无法删除根实际值版本和默认版本。

请求 URI 示例：

HTTPS://api.adaptiveplanning.com/api/rest/modeling/v1/DACCO/versions?versionName={versionName}

请求正文示例：

<留空>

查询参数

名称	描述	必填
versionName	要删除的现有版本的名称。	是
instanceCode	要从中检索值的 instanceCode。例如，GLOBO。如果未指定 instanceCode，则使用用户的默认实例。	否

路径参数

名称	描述	必填
租户	要操作的租户，例如 GREENCO	是

示例回复

204 NO_CONTENT

成功响应为空，状态代码为 204。

PATCH

请求：

/api/rest/modeling/v1/{tenant}/versions： 创建/更新实际值版本，或更新计划版本。

如果指定的版本编号存在，则更新现有的实际值/计划版本。如果没有，则使用该编号创建新的实际值版本。 查询参数当前支持两组版本标识符： -version name 对于每次调用，只需在 URL 中指定一个以上查询参数。

请求 URI 示例：

HTTPS://api.adaptiveplanning.com/api/rest/modeling/v1/DACCO/versions?versionName={versionName}

请求正文

- 包含要为现有版本更新或为要创建的新版本指定的版本属性的 JSON。

更新：

- 对于更新，请求正文中不需要任何特定属性（versionType 除外），但仍然需要请求正文。

POST

的请求正文部分列出了不同类型的计划版本的属性列表。

- 无法更新标志属性（例如，journalEntryVersion）；但是，只要它们具有正确的未更改值，它们仍然可以保留在请求正文中。

- 当前不支持父级更新。

- 更新非叶版本（具有子级的版本）时，这些版本的用户组只能具有“FULL_ACCESS”或“HIDDEN”访问类型。“FULL_ACCESS”在用户界面上显示为“可见”，两者等效。

- 通过在更新调用的请求主体中指定 groupId=0，可以移除组访问权限详细信息（组编号和组访问级别）。

创建：

- 对于 Create，可以在请求主体中指定以下属性：

属性	描述	必填（对于实际值）	必填（对于日记账分录）	请求正文中的属性名称	值类型	默认值
短名称	版本短名称	否	否	shortName	String	空字符串
父级	此版本的父级。	否	否	父级	字符串（版本名称）	根实际值版本
版本类型	版本类型（ACTUALS 或 PLANNING）	Y，实际值	Y，实际值	versionType	String
描述	描述	否	否	描述	String	空字符串
管理员访问	管理员的版本访问级别。	否	否	administratorsAccess	VersionAccessControl	继承自父级
用户访问权限	用户的版本访问级别。	否	否	userAccess	VersionAccessControl	继承自父级
实际值访问特权用户	版本访问级别：具有“实际值访问特权”权限的任何人。	否	否	privilegedActualsAccess	VersionAccessControl	继承自父级
组编号	指定的用户组编号	否	否	groupId	整数	继承自父级
组访问级别	指定用户组的版本访问级别。	是（如果指定了组编号）。	是（如果指定了组编号）。	groupAccessLevel	VersionAccessControl	继承自父级
审核线索	保留/删除审核线索信息。	否	否	auditTrail	Boolean	false（从日记账分录版本的父级继承）
日记账分录版本	要创建的版本是否为日记账分录。	否	是，正确	journalEntryVersion	Boolean
returnId	如果设置为 true，则返回版本编号。新版本编号（如果操作创建了新版本）。否则，它将返回已更新的现有版本的编号。	否	否	returnId	Boolean	false（返回 204 No Content，并将其设置为 false；如果将其设置为 true，则返回 200 OK，并在响应中包含 version）

- VersionAccessControl 值类型可采用以下字符串值："HIDDEN"、"LOCKED"、"LOCKED_EXCEPT_NOTES"、"IMPORT_AND_NOTES"、"FULL_ACCESS"。

- 可通过 exportGroups 公共 API 获取组编号。

- 已禁用合并的公司不支持日记账分录版本。

日记账分录版本属性：

以下属性位于“journalEntryVersionProperties”嵌套对象下（请参见示例请求正文），并且仅用于日记账版本：

属性	描述	必填（对于实际值）	必填（对于日记账分录）	请求正文中的属性名称	值类型	默认值
日记账分录编号	指定日记账分录的编号方式。可以为自动 (A)、手动 (M) 或无 (N)。	未使用	否	journalEntryNumbering	String	无 (N)
前缀	JE 编号的前缀	未使用	Y（如果日记账分录编号为自动 (A) 或手动 (M)）	前缀	String
起始编号	日记账分录编号的起始值	未使用	“是”，如果日记账分录编号 (A)	startingNumber	整数

特定于根实际值的属性：

以下属性仅在更新根实际值时使用：

属性	描述	必填	请求正文中的属性名称	值类型
版本开始	版本开始	否	startOfVersion	字符串（时段代码）
版本结束	版本结束	否	endOfVersion	字符串（时段代码）
开始滚动位置	版本的起始滚动位置	否	startingScrollLocation	字符串（时段代码）
完成值截止日期	计划版本上的实际值覆盖何时停止	否	completedValuesThrough	字符串（时段代码）
启用工作流	允许您在“工作流”中按层级提交实际值。	否	endableWorkflow	Boolean

请求正文示例：

请求正文
{ "parent": "Parent Version", "versionType": "ACTUALS", ... "administratorsAccess": "FULL_ACCESS", "usersAccess": "IMPORT_AND_NOTES", ... ... "auditTrail": true }

具有嵌套属性的版本（日记账分录版本和虚拟版本）的请求正文示例：

请求正文
{ "parent": "Actuals", "versionType": "ACTUALS", "shortName": "test JE version", "journalEntryVersion": "true", "journalEntryVersionProperties": { "journalEntryNumbering": "A", "prefix": "JE-Prefix", "startingNumber": "25" }, ... "auditTrail": true }

查询参数：

名称	描述	必填
versionName	要创建的新版本或要更新的现有版本的名称。	是
proceedWithWarnings	可选查询参数，用于忽略警告消息。如果未设置为 true，则在执行调用之前将返回潜在的警告。通过在 URL 中将此参数指定为 true 可忽略这些提示。	否
instanceCode	要从中检索值的 instanceCode。例如，GLOBO。如果未指定 instanceCode，则使用用户的默认实例。	否

路径参数：

名称	描述	必填
租户	要操作的租户，例如 GREENCO	是

发布访问权限属性：

以下请求主体属性仅在启用 Workday 时使用：

示例回复

204 NO_CONTENT

成功响应为空，状态代码为 204。

POST

请求：

/api/rest/modeling/v1/{tenant}/cloneVersion： 新建计划版本

通过复制源版本/默认版本来新建计划版本或预测版本，或者创建虚拟版本。 查询参数当前支持两组版本标识符： -new 版本名称 对于每个调用，只需在 URL 中指定上述一项且仅一项

请求 URI 示例：

HTTPS://api.adaptiveplanning.com/api/rest/modeling/v1/DACCO/cloneVersion?newVersionName=Budget 2012& sourceVersionName=Budget 2011& copyAllData=true& copySharedFormulasAndRules=true& copyAllOverrideFormulas=false

请求正文：

包含要为要创建的新版本指定的版本属性的 JSON。

名称	描述	必填（对于计划）	必填（对于预测）	必填（适用于虚拟）	请求正文中的属性名称	值类型	默认值
短名称	版本短名称	否	否	否	shortName	String	空字符串
父级	此版本的父级文件夹。	否	否	否	父级	字符串（文件夹名称）
版本类型	版本类型（ACTUALS 或 PLANNING）	是，正在规划	是，正在规划	是，正在规划	versionType	String
描述	描述	否	否	否	描述	String	空字符串
已锁定版本	为所有用户锁定整个版本，包括主公式和其他账户公式。	否	未使用	未使用	lockedVersion	Boolean	继承自源版本
计算公式值	适用于已选中“已锁定版本”的计划版本。用于在大多数账户中保留公式和引用的计算结果，并提高已锁定版本的性能。	否	未使用	未使用	calculateFormulaValues	Boolean	false
管理员访问	管理员的版本访问级别。	否	否	否	administratorsAccess	VersionAccessControl	继承自源版本（计划）； IMPORT_AND_NOTES（预测）；已锁定（虚拟）
用户访问	用户的版本访问级别。	否	否	否	usersAccess	VersionAccessControl	继承自源版本（计划）； IMPORT_AND_NOTES（预测）；已锁定（虚拟）
可编辑工作表权限	“版本”访问级别：具有“可编辑工作表权限”的任何用户。	否	否	否	editableSheetAccess	VersionAccessControl	继承自源版本（计划版本、预测版本）
组编号	指定用户组的编号。	否	否	否	groupId	整数	继承自源版本（计划版本、预测版本）
访问级别	指定用户组的版本访问级别。	否	否	否	groupAccessLevel	VersionAccessControl	继承自源版本（计划版本、预测版本）
左侧滚动限制	版本的左侧滚动限制	否	否	未使用	startOfVersion	字符串（时段代码）	继承自源版本
计划结束	计划结束	否	否	未使用	endOfPlan	字符串（时段代码）	继承自源版本
计划开始	计划开始	否	否	未使用	startOfPlan	字符串（时段代码）	继承自源版本
锁定提前时段	使指定时段的数据在版本中不可编辑。在用户界面上显示为“从 {leaf stratum} 起锁定到”。	否	未使用	未使用	lockLeadingTimePeriod	字符串（时段代码）	继承自源版本
锁定行首完成	上述属性的“完成 {leaf stratum}”选项。不能在请求主体中同时指定此属性和“锁定超前时段”。	否	未使用	未使用	lockLeadingCompletion	Boolean	继承自源版本
默认	将版本设为所有用户的默认版本。	否	未使用	未使用	默认	Boolean	false
审核线索	保留/删除审核线索信息。	否	否	未使用	auditTrail	Boolean	继承自源版本
实际值覆盖包括不可用的层级	显示实际值覆盖中的所有层级，包括不再使用的层级。	否	否	未使用	actualsOverlayIncludesUnavailableLevels	Boolean	false
用于覆盖的实际值版本	使用指定的实际值版本数据覆盖计划数据。	否	否	未使用	actualsVersionOverlay	字符串（版本名称）	根实际值版本
深入挖掘交易编号	允许深入挖掘版本的交易。	否	否	未使用	drillIntoTransactionId	整数	默认报告
预测版本	要创建的版本是否为预测版本。	未使用	是，正确	未使用	predictiveVersion	Boolean
虚拟版本	要创建的版本是否为虚拟版本。	未使用	未使用	是，正确	virtualVersion	Boolean
returnId	如果设置为 true，则会返回版本编号。新版本编号（如果操作创建了新版本）。否则，它将返回已更新的现有版本的编号。	否	否	否	returnId	Boolean	false（返回 204 No Content，表示为 false；如果设置为 true，则返回 200 OK，并在响应中包含 version in）

- VersionAccessControl 值类型可采用以下字符串值："HIDDEN"、"LOCKED"、"LOCKED_EXCEPT_NOTES"、"IMPORT_AND_NOTES"、"FULL_ACCESS"。

- 对于任何用户组，锁定的计划版本都不能设置为“IMPORT_AND_NOTES”或“FULL_ACCESS”。

- 不能为任何用户组将预测版本设置为“FULL_ACCESS”。

- 对于任何用户组，虚拟版本只能设置为“隐藏”或“已锁定”。

- 无法为未启用计划的启用了合并的公司创建计划版本和预测版本。

版本虚拟属性

以下属性位于 VirtualVersionProperties 嵌套对象下，仅用于虚拟版本：

名称	描述	必填（对于计划）	必填（对于预测）	必填（适用于虚拟）	请求正文中的属性名称	值类型	默认值
基础版本	将为虚拟版本提供基础数据的版本。不能是虚拟版本或子实际值版本。	未使用	未使用	否	基本版本	字符串（版本名称）	默认版本
汇率版本	将为虚拟版本（用于固定汇率报告）提供汇率的版本。不能是虚拟版本或子实际值版本。	未使用	未使用	否	exchangeRateVersion	字符串（版本名称）	根实际值版本
启用固定汇率报告	启用/禁用固定汇率报告。	未使用	未使用	否	enableConstantCurrencyReporting	Boolean	false
偏移	向后（正整数）或向前（负整数）偏移量。	未使用	未使用	否	offset	整数	0

发布访问属性

以下请求主体属性仅在启用 Workday 时使用：

名称	描述	必填（对于计划）	必填（对于预测）	必填（适用于虚拟）	请求正文中的属性名称	值类型	默认值
财务计划	为此版本启用/禁用财务计划。 仅在启用了 Adaptive Planning for Financial Plans 时使用。	否	未使用	未使用	financialPlans	Boolean	false
人员编制计划	为此版本启用/禁用人员编制计划。 仅在启用了 Adaptive Planning for Financial Plans 或 Adaptive Planning for the Workforce 时使用。	否	未使用	未使用	headcountPlans	Boolean	false
劳动力行动计划	为此版本启用/禁用劳动力行动计划。 仅在启用 Adaptive Planning for the Workforce 时使用。	否	未使用	未使用	workforceActionPlans	Boolean	false

请求正文示例

请求正文
{ "parent": "Parent Folder", "versionType": "PLANNING", "description": "Test Plan Version", ... ... "usersAccess": "LOCKED_EXCEPT_NOTES", "editableSheetAccess": "LOCKED", ... "startOfVersion": "2012", "endOfVersion": "2013", "startingScrollLocation": "01/2012", "lockLeadingTimePeriod": "02/2012", "actualsOverlayIncludesUnavailableLevels": true }

查询参数

名称	描述	必填（对于计划）	必填（对于预测）	必填（适用于虚拟）	URL 中的参数名称	默认值
源版本名称	要复制的源版本的名称。如果未指定，则从默认版本复制。	否	否	未使用	sourceVersionName
新版本名称	要创建的新版本的名称。	是	是	是	newVersionName
复制所有数据	如果为 true，则复制所有数据。	否	未使用	未使用	copyAllData	false
复制共享公式和规则	如果为 true，则复制共享公式和规则。	否	未使用	未使用	copySharedFormulasAndRules	false
复制所有重设公式	如果为 true，则复制所有重设公式。	否	否	未使用	copyAllOverrideFormulas	false
复制总分类账和自定义账户中的拆分	如果为 true，则复制总分类账和自定义账户中的拆分。	否	未使用	未使用	copySplitsInGLAndCustomAccounts	false
复制模型化行	如果为 true，则复制模型化行。	否	未使用	未使用	copyModeledRows	false
复制单元格、工作表和工作流注释	如果为 true，则复制单元格、工作表和工作流注释（如适用）。	否	未使用	未使用	copyAllNotes	false
将工作流状态重置为“正在进行”	如果为 true，则将工作流状态重置为“正在进行”。	否	未使用	未使用	resetWorkflowStatusToInProgress	false
复制审核线索历史记录	如果为 true，则将作为报告参数选项添加到所有报告。		未使用	未使用	copyAuditTrailHistory	false
作为报告参数添加到所有报告	如果为 true，则将作为报告参数选项添加到所有报告。	否	未使用	未使用	addAsReportParameterChoiceToAllReports	false
复制工作表中重新计算的值	如果为 true，则复制工作表的重新计算值。	否	未使用	未使用	copyRecalculatedValuesOfSheets	false
出现警告时继续	可选查询参数，用于忽略警告消息。如果未设置为 true，则在执行调用之前将返回潜在的警告。通过在 URL 中将此参数指定为 true 可忽略这些提示。	否	否	否	proceedWithWarnings	false
实例代码	要从中检索值的 instanceCode。例如，GLOBO。如果未指定 instanceCode，则使用用户的默认实例。	否	否	否	instanceCode	用户的默认实例

- 对于已禁用工作流的公司，不支持“将工作流状态重置为正在进行”。

- 如果“模型隔离”功能标志为“关闭”，则不支持“复制工作表的重新计算值”。

路径参数：

名称	描述	必填
租户	要操作的租户，例如 GREENCO	是

示例回复：

204 NO_CONTENT

成功响应为空，状态代码为 204。