获取卡片数据_V2
POST
/public-api/v2/card/{cardId}/data
X-Public-User-Id 指定操作用户。鉴权与操作用户
X-Public-User-Id：| 方式 | 凭证 | 要求 |
|---|---|---|
| OAuth2 应用授权 | Authorization: Bearer <access_token> | 应用获得 legacy-public-api:full-access scope，凭证和应用有效，并满足许可、IP 白名单等授权要求。 |
| 集成 Token | X-Public-Token: <集成Token> | 使用统一账户集成 Token，并满足该 Token 的校验要求。 |
X-Public-User-Id 传 Token 所属租户内的用户 loginId（登录账号），不是内部 uId；用户必须存在且启用，并具有卡片读取功能权限及目标卡片的读取权限。应用授权不会替代用户的资源权限校验。OAuth2 获取 Token
client_id 和 client_secret，通过 HTTP Basic 认证申请 Token，授权类型为 client_credentials。TOKEN_ENDPOINT 使用应用凭证返回的 tokenEndpoint；默认对外地址为 https://<BI域名>/backend/oauth2/token，以目标环境配置为准。access_token，有效期以 expires_in 为准。这里需要 OAuth2 应用访问令牌，不是登录会话 Token 或个人访问 Token（PAT）。OAuth2 查询示例
BI_BASE_URL 为 BI 服务对外 API 地址前缀；例如网关统一使用 /backend 时填写 https://<BI域名>/backend。集成 Token 查询示例
查询与分页
筛选条件字段说明
| 字段 | 说明 |
|---|---|
filters | 本次查询额外应用的字段过滤条件列表。每项通常使用 name、filterType、filterValue 描述字段、过滤方式和过滤值。服务端按 name 匹配卡片数据集字段的原名或别名，并填入对应字段 ID；多个条件共同参与查询。 |
filters[].name | 筛选字段名称。服务端用该值匹配目标卡片数据集字段的原名或别名；名称应与卡片中实际字段保持一致。若有多个同名/同别名字段，代码取首个匹配字段。 |
filters[].filterType | 过滤类型。常用值：GT 大于、GE 大于等于、LT 小于、LE 小于等于、BT 闭区间、EQ 等于、NE 不等于、IN 属于列表、NI 不属于列表；STARTSWITH/ENDSWITH/CONTAINS 分别表示以指定文本开头/结尾/包含，NOT_ 前缀表示取反；IS_NULL 为空，NOT_NULL 不为空。 |
filters[].filterValue | 过滤值列表，元素使用字符串；数值和日期也按字符串传入。例如 GT 配 ["10"]，BT 配 ["10","20"] 表示大于等于 10 且小于等于 20，IN 配 ["华东","华南"] 表示匹配任一候选值。具体值格式须与字段类型及过滤类型一致。后端模型还允许数组元素为 null，用于支持空值的过滤类型。 |
{"name":"销售额","filterType":"BT","filterValue":["10","20"]}。字段名与值须替换为目标卡片的实际字段和业务值。动态参数字段说明
| 字段 | 是否必填 | 说明 |
|---|---|---|
dpId | 是 | 动态参数 ID。使用目标卡片或数据集中已定义参数的真实 ID。 |
name | 是 | 动态参数名称，与参数定义保持一致。 |
valueType | 是 | 动态参数值类型。常用 NUMBER（数值）、DATE（日期）、STRING（字符串）；后端模型将此字段作为字符串读取，未在此处限定枚举。 |
defaultValue | 否 | 本次查询使用的参数值。必须按字符串传入，例如数值参数传 "25"；此接口通过该字段读取传入值。 |
fdId | 否 | 动态参数应用的字段 ID，可选。 |
customize | 否 | 是否为自定义动态参数，可选。 |
multiple | 否 | 是否为多值动态参数，可选。defaultValue 仍是字符串，应与已有参数配置约定保持一致。 |
optionValue | 否 | 动态参数的可选值列表，可选。 |
inheritParent | 否 | 是否继 承父作用域参数，可选。 |
paramType | 否 | 作用域参数类型：WORKFLOW 为工作流参数，DATADRIVEN 为数据驱动参数；可选。 |
defaultValue 传入，数值也使用字符串；不要另起 value 字段。省略 dynamicParams 时沿用卡片已有动态参数配置。zoneFilter（自助取数查询配置）
zoneFilter 是自助取数专用查询参数，放在请求体顶层，为可选对象，也可传 null。它只作用于本次取数，不保存卡片配置。参数结构
| 字段 | 类型 | 说明 |
|---|---|---|
| zoneData | object | 本次查询的行、列、指标、表头筛选和排序布局。 |
| zoneData.row / column / metric | array<object> | 字段条目包含key、name、metaType；实际按卡片字段key匹配。 |
| zoneData.filters | array<object> | 表头筛选：key、filterType、filterValue；还支持name、metaType、advFilter、advFilterContent、filterLevel、aggrType。 |
| zoneData.sorting | array<object> | 排序：key、ordering（asc/desc）；还支持name、metaType、customSort、isPinYinOrder。 |
| detailMode | boolean | true按明细模式查询；省略或false走普通透视模式。 |
| hasGrandTotalOnRow / hasGrandTotalOnColumn | boolean | 普通透视模式的行/列区域总计开关。 |
| grandTotal | object | onRow.position为TOP/BOTTOM；onColumn.position为LEFT/RIGHT，均使用字符串。 |
| cellMerge | object | noMergeColumn、noMergeRow分别控制是否取消列/行单元格合并。 |
| excludeConditionConfig | object | allResultsAreZero、resultsSumAreZero、allResultsAreNull和filterLevel（DETAIL/AGGREGATION/RESULT）。 |
zoneFilter 参数树。除字段条目实际需要key外，其他子字段按需传入；可选字段也接受null，数组中的字段条目应为对象。使用时的关键区别
1.
2.
3.
{ "turnedOn": true, "sortOrder": ["华东", "华南"], "sortUnspecifiedValues": true }，turnedOn=true且sortOrder非空时才启用。4.
5.
示例一：保留原字段，按明细模式取数
{
"view": "GRAPH",
"zoneFilter": {
"detailMode": true
}
}示例二：选择区域字段，筛选并排序
{
"view": "GRAPH",
"offset": 0,
"limit": 100,
"zoneFilter": {
"detailMode": false,
"zoneData": {
"row": [
{
"key": "<ROW_FIELD_KEY>"
}
],
"column": [],
"metric": [
{
"key": "<METRIC_FIELD_KEY>"
}
],
"filters": [
{
"key": "<ROW_FIELD_KEY>",
"filterType": "IN",
"filterValue": [
"华东",
"华南"
]
}
],
"sorting": [
{
"key": "<METRIC_FIELD_KEY>",
"ordering": "desc"
}
]
}
}
}示例三：总计与合并设置
{
"view": "GRAPH",
"zoneFilter": {
"detailMode": false,
"hasGrandTotalOnRow": true,
"hasGrandTotalOnColumn": true,
"grandTotal": {
"onRow": {
"position": "BOTTOM"
},
"onColumn": {
"position": "RIGHT"
}
},
"cellMerge": {
"noMergeColumn": true,
"noMergeRow": true
}
}
}返回数据的读取方式
chartMain.data 为单元格矩阵，结合 row 与 column 的元信息和表头读取；单元格的 v 是原始值，显示格式由对应格式配置解释。row、column 的表头、格式索引和字段标识用于解释结果布局；这些并非数据集字段清单的另一份副本。chartMain.meta.axes 为卡片显示配置透传；没有在该后端接口中定义的单位、枚举和前端渲染细节不作额外约束。常见错误
| 情况 | 响应判断 |
|---|---|
| 用户 不存在或停用、卡片不存在、无读取权限 | 通常 HTTP 200，result=fail，读取对象 error 中的业务错误码及消息。 |
| 集成 Token 缺失或无效 | 通常 HTTP 403，返回 result/response/error 包络。 |
| OAuth2 Token 无效、过期或未通过认证 | HTTP 401，error 为字符串；具体原因见 message。 |
| OAuth2 scope 不足或应用授权校验失败 | HTTP 403，error 为字符串，例如 insufficient_scope；具体原因见 message。 |
| OAuth2 应用调用超过限制 | HTTP 429，读取顶层 error、message、status。 |
result 判断所有失败响应。请求参数
Path 参数
Header 参数
Body 参数application/json
请求示例代码
返回响应
修改于 2026-11-03 02:54:40