customReportValues
在 API v37 中进行了更新。
种类 | 数据检索 |
描述 | 在所请求的实例中，返回符合所请求报告条件的一组数据。 |
调用所需的权限 | 无（必须为用户指定权限集） |
请求时需要的参数 | 凭据，报告 |
对于 API 版本 15 及更高版本，请调用 exportTime 以检索正确的时间元素编号。
请参见 参考信息：customReportValues 性能条件 ，了解如何确保您的请求利用 2023R2 中针对 API v36 发布的性能和可扩展性改进。
此方法的请求包含可用于搜索数据和返回值的报告规范。此 API 将内部编号作为输入。可以调用元数据检索 API 来获取有效编号。结果由坐标和值表示。如果适用，响应还会返回警告和错误消息。
此 API 基于矩阵报告。此请求要求调用方在 X 轴（列）和 Y 轴（行）以及用于筛选 API 检索的所有数据的可选筛选器轴上指定元素。矩阵报告包含轴，用于确定报告中显示的数据。每个轴都定义了报告的一个边。所有矩阵报告都具有三个轴：
- X 轴（上边缘）它定义报告中的列集。
- Y 轴（左侧边缘）定义报告中的行集。
- 筛选器轴，这是一个全局轴，用于定义适用于报告中所有数据的属性。有关更多信息，请参见筛选轴示例。
一个轴可以分为多个段。“段”是一种在单个轴上分隔维度集的方法。筛选器轴只能有一个段，但其他两个轴可以有任意多的段。
每个段可以具有不限数量的阶梯。“层”表示单个逻辑维度，用于描述该维度的哪些元素适用于其下的行或列。对于每个逻辑维度，段最多只能包含一个层。
每个层都可以包含一个或多个层维度元素。（层中的所有元素都必须属于层中指定的维度。）元素通常是维度中的条目，例如账户维度中的特定账户，或时间维度中的会计季度。然后，系统会使用这些元素来选择和聚合在报告中找到的数据。
当 X 轴或 Y 轴上的段包含多个层时，每个层的元素将与所有其他层的所有元素组合，以形成层元素所有可能组合的笛卡尔积。每一列或行表示一种可能的元素组合，从每一层中选择一个元素。例如，如果 X 轴上的某个段（即顶部的列）包含一层（含五个元素）和第二层（含两个元素），则该段将生成 10 列，分别表示 X 轴上元素的所有可能组合。阶梯您不能将一个元素类型放置在多个轴上。例如，如果您将账户元素类型放置在行中，则无法在列或筛选器上添加账户。
层可以同时包含单个元素或汇总元素。汇总元素可汇总在其下指定的所有元素。筛选器中不允许使用汇总元素。
筛选轴的作用与 X 轴和 Y 轴非常相似，但有一个细微的区别：由于筛选轴适用于报告中的所有数据，因此它不能将其层组合起来形成多个行或列。相反，筛选轴会组合每个层的所有元素，将所有元素的数据聚合在一起，就好像这些元素汇总到单个聚合中一样。
请参见 创建基本矩阵报告 有关段、轴和维度元素的更多信息，请参见
筛选轴示例
以下示例显示了筛选器轴的所有可能元素。
<axis type="FILTER"> <segment> <!-- Account filter --> <tier type="acct"> <el id="258" /> </tier> <!-- Time filter --> <tier type="time"> <el id="342" /> </tier> <!-- Level filter --> <tier type="lvl"> <el id="354" /> </tier> <!-- Version filter --> <tier type="ver"> <el id="385" offset="1" offset-strata="2"/> </tier> <!-- Currency filter --> <tier type="cur"> <el id="448" /> </tier> <!-- Account Attribute filter --> <tier entity-id="23" type="aAttr"> <el id="512" /> </tier> <!-- Level Attribute filter --> <tier entity-id="25" type="lAttr"> <el id="607" /> </tier> <!-- Dimension Attribute filter --> <tier entity-id="21" type="dAttr"> <el id="649" /> </tier> <!-- Dimension filter --> <tier entity-id="1" type="dim"> <el id="717" /> </tier> </segment> </axis>
申请格式
您可以在此处找到请求的 XML 架构：customReportValues REST 规范。
<?xml version='1.0' encoding='UTF-8'?> <call method="customReportValues" callerName="a string that identifies your client application"> <credentials login="sampleuser@company.com" password="my_pwd" locale="fr_FR" instanceCode="INSTANCE1"></credentials> <requestInfo> <!-- Add elements here that we want to show up in the ELK logs --> </requestInfo> <report suppress-zeroes="1" include-element-code="1"> <!-- Run report suppressing blanks, but not zero values. Add calc element codes to the response --> <!-- columns --> <axis type="X"> <segment> <!-- time columns --> <tier type="time"> <!-- Timespan creates multiple time columns from Jan-2014 to Dec-2014.Ids specified in timespan element are retrieved from exportTime API output. 'show-time' is a mandatory attribute specifying list of strata ids --> <el complex-type="timespan" end="179001" start="168001" show-time="3,2,1"/> <el id="180001" /> <!-- single column of Jan 2015 . This id is retrieved from exportTime API output--> <subtotal code="Subtotal" /> <!-- subtotal of the output of all the time elements left of this subtotal element --> </tier> </segment> </axis> <!-- rows --> <axis type="Y"> <segment> <!-- There are 2 tiers with 2 elements and 4 elements, respectively. Without considering expansion, this generates 8 rows of: 1. dimension value with id 135, account with id 51 2. dimension value with id 135, account with id 53 3. dimension value with id 135, difference between account with id 51 and account with id 53 4. dimension value with id 135, calculation using the formula - Sum of account with id 51 and the output of the difference element from previous row 5. dimension value with id 199, account with id 51 6. dimension value with id 199, account with id 53 7. dimension value with id 199, difference between account with id 51 and account with id 53 8. dimension value with id 199, calculation using the formula - Sum of account with id 51 and the output of the difference element from previous row. Assume dimension value 135 has child 150, which has children 160,161,162. Dimension value 199 has child 200, which has children 210,211,212. With expansion, element of dimension value 135 with rollup-mode 'D' and 'suppress-elt-rollup' would yield to {135,160,161,162}. Element of dimension value 199 with 'rollup-mode' 'X' and 'start-expanded' 199,200 would yield to {199,200,210,211,212}. In total, there will be 9 x 4 = 36 rows in cartesian without suppress zero. --> - <tier entity-id="13" type="dim"> <!-- dimension values with id 135 and 199 from dimension with id of 13 --> <el id="135" rollup-mode="D" suppress-elt-rollup="1"/> <!-- Expand to Leaves operation on tag dimension id=135, return "Leaves + root" --> <el id="199" rollup-mode="X" start-expanded="199,200"/> <!-- Custom expansion with start expanded on tag dimension id=199 and 200, where 200 is a child of 199, return 199 and the the immediate children of 199 and 200 --> </tier> <tier type="acct"> <!-- account with id of 51 and 53 --> <el id="51" /> <el id="53" /> <diff operand-a="51" operand-b="53" code="Difference" /> <!-- difference between account with id 51 and account with id 53 --> <calc formula="[51]+RPT.Difference" /> <!-- calculation using the formula - Sum of account with id 51 and the output of the difference element (previous element) --> </tier> </segment> </axis> </report> </call>
此 API 的每次调用都必须恰好包含以下每种列出类型的一个元素：
credentials
报告
凭据元素 | |||
标记名称 | credentials | ||
描述 | 所有 API 调用都必须包含一个凭据元素，以识别调用 API 的用户。然后，系统会以此用户身份执行 API 调用（系统中的任何审核线索或操作历史记录都将显示此用户执行了该操作），因此，用户必须具有执行该操作所需的权限，才能执行 API 调用。成功。 | ||
元素的属性 | |||
属性名称 | 必填？ | 值 | 示例 |
登录 | 是 | 调用 API 方法的用户的登录名。此用户必须具有所需的权限才能调用此方法 | sampleuser@company.com |
password | 是 | 调用 API 方法的用户的密码。 | my_password |
locale | 否 | 指定用于解释传入数字和日期的区域设置，以及用于设置传出数字和日期格式的区域设置（使用正确的千位分隔符、月份名称和日期格式）。区域设置还用于指定回复中的任何系统消息应使用的语言。如果未指定，则使用 en_US（美式英语）。 | fr_FR |
instanceCode | 否 | 如果凭据中指定的用户有权访问多个实例， Adaptive Planning ，此属性可用于指定用户打算访问默认实例以外的实例。如果未指定，则将使用用户的默认实例。要确定可用的实例代码，请使用 exportInstances API。 | MYINSTANCE1 |
元素的内容 | |||
（无） | |||
报告元素 | |||||||||||
标记名称 | 报告 | ||||||||||
描述 | 指定构成报告的元素。 | ||||||||||
元素的属性 | |||||||||||
属性名称 | 必填？ | 值 | 示例 | ||||||||
suppress-zeroes
在 API v37 中进行了更新。 | 否 | 此属性用于管理行级别的数据隐藏。指定此项将控制输出是否包含零行或空行。有效值为 0（不显示任何内容 - 显示所有行）、1（不显示空值 - 不显示仅包含空白单元格的行）和 2（不显示空值和零 - 不显示仅包含空白或零值单元格的行）。如果未指定此属性，则默认值为 2。如果单元格浏览器中某个单元格的值为空，则该单元格将被视为空白。 此属性与“cell-inclusions”属性结合使用。请参见“cell-inclusions”来查看默认行为。 | 0 | ||||||||
单元格包含项
适用于 API v37。 | 否 | 此属性根据“suppress-zeroes”属性的指示，在单元格级别对所有未隐藏的行进行管理。指定此项将控制输出是否包含零单元格或空白单元格。有效值为 0（包含全部 - 显示所有单元格）、1（包含数据和零 - 排除空白单元格）和 2（仅包含数据 - 排除零和空白单元格）。 默认行为：如果未指定此属性，则默认行为由“suppress-zeroes”属性决定。 “suppress-zeroes”属性值不同时的表现：
| 0 | ||||||||
show-cell-notes | 否 | 如果指定此属性，此属性会显示或隐藏单元格注释。0=不显示单元格注释（默认），1=显示单元格注释 | 1 | ||||||||
suppress-rollups | 否 | 如果指定此属性，则此属性会显示或隐藏汇总行和列。系统仅针对子女出现在报告中的父级，不显示汇总行和汇总列。有效值为 0（不显示汇总）或 1（不显示汇总）。默认值为 0。 | 1 | ||||||||
include-element-code | 否 | 如果给定，此属性会添加或隐藏“计算（小计、差异和计算）”元素的代码。有效值为 0（不向输出添加计算元素的代码）或 1（向输出添加计算元素的代码）。默认值为 0。 | 1 | ||||||||
元素的内容 | |||||||||||
有关更多详细信息，请参见申请格式。 | |||||||||||
回复格式
您可以在 customReportValues REST 规范中找到响应的 XML 架构。
<?xml version="1.0" encoding="utf-8"?> <response success="true"> <messages> <!-- Dimension value id 13 is invalid. Rows with value id 13 has been removed from the report. --> <message type="WARNING" key="invalid-dim-attr-id" values="199,13">Invalid value Id 199 for dimension/attribute type id 13 </message> </messages> <!-- Global filters. Although the request did not supply any filters, defaults are used when dimension types are not specified. Reporting against version with id 2 which is the current version. Level with id 1 is the top most level this user has access to. --> <filters> <coords> <coord type="ver" rollup="1"> <el id="2" /> </coord> <coord type="lvl" rollup="1"> <el id="1" /> </coord> </coords> </filters> <!-- Only two time columns Dec-2014 and Jan-2015 have data, all other columns have been removed --> <cols> <col id="1"> <coords> <coord type="time"> <el id="179001" /> </coord> </coords> </col> <col id="2"> <coords> <coord type="time"> <el id="180001" /> </coord> </coords> </col> <col id="3"> <coords> <coord code="Subtotal" type="subtotal" /> </coords> </col> </cols> <rows> <row> <!-- Row coordinates are account with id 51 and dimension value with id of 135 from dimension with id of 13 --> <coords> <coord type="acct"> <el id="51" /> </coord> <coord type="dim" entity-id="13"> <el id="135" /> </coord> </coords> <cell value="2.345" col="1" /> <!-- This value’s coordinates are the row coordinates listed above, matches column position 1 and the global filters. --> <cell value="2.345" col="2" /> <!-- This value’s coordinates are the row coordinates listed above, matches column position 2 and the global filters. --> <cell value="4.69" col="3" /> <!-- This value’s coordinates are the row coordinates listed above, matches column position 2 and the global filters. --> </row> <row> <!-- Row coordinates are account with id 53 and dimension value with id of 135 from dimension with id of 13 --> <coords> <coord type="acct"> <el id="53" /> </coord> <coord type="dim" entity-id="13"> <el id="135" /> </coord> </coords> <cell value="5.34" col="1" /> <!-- This value’s coordinates are the row coordinates listed above, matches column position 1 and the global filters. --> <cell value="7.44" col="2" /> <!-- This value’s coordinates are the row coordinates listed above, matches column position 2 and the global filters. --> <cell value="12.78" col="3" /> <!-- This value’s coordinates are the row coordinates listed above, matches column position 2 and the global filters. --> </row> <row> <coords> <coord code="Difference" type="diff" /> <coord type="dim" entity-id="13"> <el id="135" /> </coord> </coords> <cell value="2.995" col="1" /> <cell value="5.095" col="2" /> <cell value="8.09" col="3" /> </row> <row> <coords> <coord type="calc" /> <coord type="dim" entity-id="13"> <el id="135" /> </coord> </coords> <cell value="5.34" col="1" /> <cell value="7.44" col="2" /> <cell value="12.78" col="3" /> </row> </rows> </report> </output> </response>
回复元素 | |||
标记名称 | 回复 | ||
元素的属性 | |||
属性名称 | 必填？ | 值 | 示例 |
成功 | 是 | true 或 false，指示 API 调用是否成功。即使成功调用，响应中也可能包含警告消息。 | True |
已废弃 | 否 | 如果此属性出现在响应标记中并设置为 true，则表示正在调用的方法或 API 的版本已过时，已被正式弃用。虽然此时它仍可继续运行，但可能会在短时间内停止运行。通常情况下，此属性不存在。 | false |
元素的内容 | |||
一个可选的 messages 元素，以及一个必需的输出元素。 | |||
messages 元素 | |
标记名称 | 消息 |
描述 | 一个或多个消息元素的容器。 |
元素的属性 | |
（无） | |
元素的内容 | |
一个或多个消息元素 | |
消息元素 | |||
标记名称 | 消息 | ||
描述 | 表示从系统发回给调用方的消息。消息用于在请求未成功时显示错误消息，在请求成功时显示警告消息，在成功时显示确认消息。 | ||
元素的属性 | |||
属性名称 | 必填 ？ | 值 | 示例 |
type | 是 | “类型”是一种标识消息类型的方法。不同的类型包括 INFO、WARNING 和 ERROR。类型“ERROR”表示此申请未处理。 | 警告 |
键 | 是 | 密钥是一种标识特定消息或消息类型的方法，可用于在客户端程序中自动记录错误并进行恢复。在不同的请求区域设置下，即使消息的语言发生变化，键也不会发生变化。关键字在将来也不太可能因措辞调整或术语变更而发生变化。 | warning-invalid-time-span-start |
值 | 否 | 如果给定，这些值表示消息文本中使用的变量。 | 199,12 |
元素的内容 | |||
消息的文本。此文本使用请求中指定的区域设置的语言（假设该区域设置受支持）。文本还可能包含可变信息，例如已处理的行数，或者导致错误的特定列或值。 | |||
请参见 概念：自定义计算的公式语法和规则