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

Modeled Sheet Definition

URL 端点

HTTPS://api.adaptiveplanning.com/api/rest/modeling/<version>/<tenant>/sheet/modeled/definition
版本：v1
种类
数据提交
描述
元数据修改
调用所需的权限
模型管理访问权限
模型包括：工作表、账户、维度和公式
请求时必须提供参数
名称

支持的 HTTP VERB

HTTP 谓词
单一资源
收款资源
描述
PATCH
支持
不支持
插入或更新模型化工作表定义
DELETE
支持
不支持
删除模型化工作表定义
POST
支持
不支持
更新插入模型化工作表定义的验证模式
选项
支持
不支持
返回此集合资源支持的 HTTP 谓词列表。

PATCH

请求 URI
/sheet/modeled/definition
更新与提供的查询参数匹配的模型化工作表定义。
如果不存在具有匹配编号的工作表，则系统将新建一个具有给定属性的模型化工作表。
请求示例（按名称）
https://api.adaptiveplanning.com/api/rest/modeling/v1/globosales/sheet/modeled/definition?name=Capital Model
请求标头示例
接受-语言：en
请求正文示例
请参见“请求正文”版块
查询参数
名称
描述
必填
instanceCode
要从中检索值的 instanceCode。例如，GLOBO。如果未指定 instanceCode，则使用用户的默认实例。
否
名称
工作表的名称。
否
proceedWithWarnings
更新插入操作是否应忽略任何警告验证，当更改后的工作表属性可能会从工作表中删除数据时，通常会返回该警告。
否
reorderColumns
将此查询参数设置为 true 将更改列列表的顺序，以反映 API 请求主体中给定的列顺序。默认情况下，此选项设置为 false。请参见 Reference: Re-ordering Columns for Modeled and Cube Sheet Definition JSON APIs。
否
请求正文
请求正文示例
两个端点的 JSON 负载使用相同的模型化工作表定义格式。
申请格式
 
{
  "properties": {
      "description": "Capital Model",
      "prefix": "Capital"
  },
  "columns": [
      {
          "properties": {
              "code": "Base Pay",
              "name": "Base Pay",
              "type": "TEXT_SELECTOR",
              "values": ["value1", "value2"],
              "lookupTables": [
                  {
                      "name": "valueLookup1",
                      "type": "VALUE",
                      "decimalPrecision": 1,
                      "displayAs": "CURRENCY"
                  },
                  {
                      "name": "spreadLookup1",
                      "type": "SPREAD",
                      "decimalPrecision": 0,
                      "displayAs": "NUMBER"
                  }
              ]
          },
          "availability": [
              {
                  "name": "100k",
                  "code": "100k",
                  "available": true
              }
          ],
          "defaultAvailability": false,
          "defaultActionIfDataIsPresent": "delete"
      },
      {
          "properties": {
              "code": "Label",
              "name": "Label",
              "type": "TEXT"
          },
          "delete": true
      }
  ],
  "accounts": [
      {
          "name": "AccountName",
          "code": "AccountCode"
      }
  ],
  "accessibility": {
      "usernames": [ "test@greenco.com" ],
      "excludedFromWorkflow": true
  }
}
工作表定义对象
名称
描述
必填
属性
包含常规工作表属性的对象
否
列
模型化工作表列对象的列表。
系统将在工作表定义的末尾创建新列，并遵循新列的相对顺序。
现有列只会就地更新；系统将不会对它们重新排序。
否
账户
账户对象列表
否
辅助功能
该对象包含用于定义按用户指定的工作表的辅助功能。
否
工作表属性对象
名称
描述
必填
类型
默认
描述
工作表描述
否
字符串
空字符串
代码
工作表代码（用于为账户代码和第二唯一编号添加前缀）。创建新工作表时为必填项。
否
字符串
前缀
用于账户代码的工作表前缀。创建新工作表时为必填项。已弃用，已改用 code。
否
字符串
userAssigned
工作表是按用户指定的工作表，还是按层级指定的工作表（默认情况下）。
否
布尔值
false
salaryDetail
工作表是否包含工资详细信息。
否
布尔值
false
frozenColumnCount
否
整数
0
allowSplits
工作表是否允许拆分行。
否
布尔值
false
allowRollupModelEdits
查看汇总层级时，工作表是否允许编辑。
否
布尔值
false
allowActuals
工作表在实际值版本中是否可用。
否
布尔值
false
recalculateOnDemand
是否为工作表启用了“按需重新计算”。
否
布尔值
false
timeStratumCode
与工作表中的数据关联的时间层级代码。
否
字符串
总分类账时间层级
工作表列对象
名称
描述
必填
类型
默认
属性
包含工作表列属性的对象。
是
对象
空闲情况
当前列的工作表可用性对象列表。请参见 Sheet Availability ，查看有关列表格式的详细信息。
否
list
defaultAvailability
要应用于所有值的默认可用性，除非在可用性中另行指定。对层级列和维度列有效。
对于维度列，如果未指定可用性或指定了“defaultAvailability”，则新列的“defaultAvailability”将设置为“true”。
默认情况下，此值为空，这意味着除非通过可用性专门进行更改，否则现有可用性将被保留。
否
布尔值
defaultActionIfDataIsPresent
除非在可用性中另有指定，否则删除值时存在数据时的默认操作。对维度列有效。
如果现有列的“Default Availability”为“false”，则为必填。
否
字符串
删除
请求从给定工作表中删除列。不适用于以下列：依赖于未标记为删除的现有列的列（例如维度属性）。
否
布尔值
工作表列属性对象
名称
描述
必填
类型
默认
名称
列名称
否
字符串
代码
列代码。除层级和层级币种列外，所有列均为必填。
是
字符串
type
列的类型
可能的值：LEVEL、DIMENSION、LEVEL_ATTRIBUTE、DIMENSION_ATTRIBUTE、TIMESPAN、NUMBER、DATE、TEXT、TEXT_SELECTOR、LEVEL_CURRENCY、DISPLAY、INITIAL_BALANCE、CHECKBox
是
字符串
只读
当前列是否为只读。对于维度属性列，请将“readOnly”设置为“false”，以将该属性用作维度的筛选器。
对于层级属性和显示列，必须为 true（默认为 true）。
否
布尔值
false
allowSplits
当前列是否可拆分。仅当常规的 allowSplits 属性为 true 时，对工作表有效。
否
布尔值
false
showTotalsAtBottom
是否在工作表底部显示此列的总计。
否
布尔值
false
allowHidden
是否可以在“显示选项”中对工作表查看器隐藏此列。对除文本选择器列和时间跨度列外的所有列有效。
否
布尔值
True
editableOnSheet
是否可以将新值添加到工作表中的维度列。仅对维度选择器列和文本选择器列有效。
否
布尔值
false
必填
是否要求每行在此列中都有一个值。仅对 allowHidden 为 false 的维度列有效。
否
布尔值
false
recalculateOnMatch
是否在匹配时重新计算值。仅适用于 recalculateOnDemand 为 true 的工作表的有效维度和文本选择器列。
否
布尔值
false
lookupTables
LookupTable 对象列表，用于定义分摊查询和值查询。仅对维度选择器列和文本选择器列有效。
否
LookupTable
null
值
要添加为文本选择器值的字符串列表。仅对文本选择器列有效。
否
字符串数组
null
rowKey
此列是否可用作行键。仅对文本驱动程序列有效。
否
布尔值
false
displayAs
列的“显示格式”。仅对数值驱动程序列有效。
可能的值：NUMBER、PERCENT、CURRENCY
否
显示格式
false
decimalPrecision
要显示的小数精度。仅对数值驱动程序列有效。
可能的值：0 到 9，或 -1（在显示为“币种”时使用币种精度）。
否
整数
0
showToggle
是否将复选框列显示为切换开关。仅对复选框列有效。
否
布尔值
false
showInEditMode
是否在模型化工作表的可编辑行中显示列。仅对层级币种列有效。
否
布尔值
false
referenceTimePeriod
指示显示列的参考时段。仅对账户显示列有效。
可能的值：FIRST_NON_ACTUALS_PERIOD、START_OF_PLAN
否
字符串
FIRST_NON_ACTUALS_PERIOD
startOfRollupRange
指示时段汇总范围在显示列中的起始位置。仅对账户显示列有效。
可能的值：CONTAINING_REFERENCE_PERIOD、BEFORE_REFERENCE_PERIOD、AFTER_REFERENCE_PERIOD
否
字符串
CONTAINING_REFERENCE_PERIOD
timePeriodsInRollupRange
显示列的汇总范围中包括的时段数量。仅对账户显示列有效。
否
整数
1
startOfRollupRangeTimeStratumCode
时段代码，用于确定显示列的汇总范围的开始日期。仅对账户显示列有效。可能的值包括等于或高于工作表时间层级的时间层级。
否
字符串
工作表时间层级
accountCode
账户代码，以确定显示列的模型化账户。仅对显示列有效。仅有效值为给定模型化工作表上的账户
否
字符串
工作表列查询表对象
名称
描述
必填
类型
默认
名称
查询表名称
是
字符串
displayAs
此查询表的“显示格式”。可能的值：NUMBER 和 PERCENT。仅对值查询表有效。
否
字符串
NUMBER
decimalPrecision
此查询表中值的小数精度。可能的值：0 到 9。
否
整数
0
type
查询表的类型。可能的值：VALUE、SPREAD。
是
字符串
工作表账户对象
有关更多详细信息，请参见 Reference: Properties in Account JSON Import Payload
名称
描述
必填
名称
账户名称
是
代码
账户代码。
是
父级
父级账户
否
描述
账户描述。
否
isCuculative
返回该账户是否为累计账户。
否
isActualsByDelta
返回账户是否为按差额输入的实际值。
否
isLink
返回此值用于判断账户是否为源关联账户。
否
timeRollupType
要对时间汇总执行的汇总类型。
否
timeWeightAccount
用于时间汇总的权重账户。
否
levelDimRollupType
要对层级/自定义维度汇总执行的汇总类型。
否
levelDimWeightAccount
用于层级/自定义维度汇总的权重账户。
否
levelDimRollupText
在层级/自定义维度汇总中使用的汇总文本值。
否
actualsOverlay
账户的实际值覆盖设置。
否
attributeValues
此账户的账户属性值对象列表。
否
displayAs
账户的显示格式设置。
否
公式
账户公式
否
WeightedAverageTranslationsEnabled
返回账户是否启用了加权平均折算。
否
weightedAverageTranslationResetStratum
此账户的加权平均折旧剩余时间层级。
否
weightedAverageTranslationTransferAccount
此账户的“加权平均折算转账账户”。
否
decimalPrecision
账户的默认小数精度。
否
exchangeRateType
此账户的汇率类型。
否
suppressZeros
返回是否应为工作表上的账户隐藏零行。
否
startExpanded
返回账户在工作表上是否开始展开。
否
dataEntryType
此账户的数据输入类型设置。
否
dataPrivacy
此账户的数据隐私设置。
否
hasSalaryDetail
返回账户是否具有工资详细信息。
否
isBreakbackEligible
返回此账户是否符合摊回条件。
否
isSystemAccount
返回此账户是否为系统账户。
否
isIntercompany
返回此账户是否为公司间账户。
否
isAssumation
返回此账户是否为假设账户。
否
isMetric
返回该账户是否为指标账户。
否
modeledSheetSpreadCode
关联模型化分摊的模型化工作表分摊代码。
否
spreadTargetAccount
分摊账户的目标账户对象。
否
工作表辅助功能对象
名称
描述
必填
类型
默认
用户名
要添加到工作表的用户名列表。
必须采用有效电子邮件地址的形式。
否
字符串数组
excludedFromWorkflow
更新了工作表辅助功能设置中的
“不列入工作流”
 复选框
否
布尔值
false
示例回复
204
成功回复为空，状态代码为 204。

DELETE

请求 URI
/sheet/modeled/definition
删除与给定查询参数匹配的模型化工作表定义。如果不存在具有匹配编号的工作表，则会出现“未找到”错误。
请求示例（按名称）
https://api.adaptiveplanning.com/api/rest/modeling/v1/globosales/sheet/modeled/definition?name=Capital Model
请求标头示例
接受-语言：en
请求正文示例
<无>
查询参数
名称
描述
必填
名称
模型化工作表的名称。
否
instanceCode
要从中检索值的 instanceCode。例如，GLOBO。如果未指定 instanceCode，则使用用户的默认实例。
否
示例回复
204
成功响应为空，状态代码为 204。

POST

请求 URI
/sheet/modeled/definition/validate
验证模型化工作表定义请求。
请求示例（按名称）
https://api.adaptiveplanning.com/api/rest/modeling/v1/default/sheet/modeled/definition/validate?name=My Sheet
请求标头示例
接受-语言：en
请求正文示例
<在下方记录>
查询参数
查看正在验证的相关端点（即 PATCH）。
请求正文
请求正文示例
所验证端点的 JSON 负载使用相同的模型化工作表定义格式。但是，对象
validationOptions
 发送验证请求时，负载中必须包含此字段。
申请格式
 
{

  "validationOptions": {
      "httpMethod": "Patch",
      "dependentDimensions": [
          "MyTestDim1", "MyTestDim2"
      ],
      "dependentAttributes": [
          {
              "attributeName": "MyTestAttr1",
              "attributeType": "DIMENSION_ATTRIBUTE",
              "dimensionName": "MyTestDim2"
          },
          {
              "attributeName": "MyTestAttr2",
              "attributeType": "LEVEL_ATTRIBUTE"
          }
      ]
  },

  "properties": {
      "description": "Capital Model",
      "prefix": "Capital"
  },
  "columns": [
      {
          "properties": {
              "code": "Base Pay",
              "name": "Base Pay",
              "type": "TEXT_SELECTOR",

...
验证选项对象
名称
描述
必填
httpMethod
指定要验证哪个模型化工作表 API 端点。当前支持以下端点：
  • PATCH
是
dependentDimensions
验证时假设存在的维度名称列表。维度不会作为验证请求的结果而保存。假设所有相关自定义维度均为单层维度。
否
dependentAttributes
相关属性对象的列表。属性不会作为验证请求的结果而保存。
否
后序属性对象
名称
描述
必填
attributeName
依赖属性的名称。
是
attributeType
依赖属性的类型。支持的类型包括：
  • LEVEL_ATTRIBUTE
  • DIMENSION_ATTRIBUTE
是
dimensionName
依赖属性的维度名称。仅适用，并且对于维度属性为必填项。不允许用于层级属性。
否