数据服务

数据服务将 VeryReport 中已发布的数据集封装为标准化 REST 查询接口，供第三方系统在服务端通过开放 API + HMAC 签名安全取数。

适用角色：数据分析师（配置 API）、系统集成开发（对接调用）。

一、能做什么

• 把数据集查询能力以 GET/POST /api/open/v1/data-service/{apiName}/query 对外暴露
• 支持配置请求过滤参数、返回字段裁剪与排序
• 管理端在线调试，无需写代码即可验证数据
• 发布 / 下线生命周期管理，与开放 API 统计打通

二、整体流程

① 在数据建模中创建并发布数据集
        ↓
② 开放平台 → 数据服务 → 创建 API
        ↓
③ 配置请求参数与返回字段
        ↓
④ 在线调试，确认有数据
        ↓
⑤ 发布 API
        ↓
⑥ 业务服务端以 HMAC 签名调用开放 API 取数

三、进入数据服务

1. 使用具备开放平台权限的账号登录 VeryReport。
2. 左侧菜单进入 「开放平台」。
3. 点击子菜单 「数据服务」，或直接访问 /open/data-service。

若看不到菜单，请联系管理员开通 open:* 相关权限。

四、前置准备：数据集

1. 在 数据建模 中创建数据集并完成表/SQL 配置。
2. 使用 数据预览 确认能查到预期数据。
3. 将数据集 发布（未发布的数据集无法被数据服务选用或调用）。

五、创建 API

5.1 第一步：配置基础信息

点击 「创建 API」，填写：

完成后点击 「下一步」。

5.2 第二步：添加 API 参数

请求参数（可选）

若调用方需按条件过滤，点击「添加请求参数」：

无过滤需求可留空，直接配置返回参数。

返回参数（建议配置）

点击 「添加返回参数」，将需要对外暴露的列逐一添加；「绑定字段」请从数据集预览中复制准确列名。

返回条数

设置单次查询最大返回行数（默认 1000，可按需调整）。

底部可 「保存」 或 「保存并调试」（保存后直接进入调试页）。

六、API 列表

支持按名称搜索、按状态（草稿 / 已发布）筛选。

操作：编辑、调试、发布 / 下线、删除。

七、在线调试

在列表点击 「调试」，或创建时选择「保存并调试」。

调试成功应看到非空的 JSON 或表格数据。调试不校验 API 发布状态，但会校验关联数据集已发布。

八、发布与下线

8.1 发布

1. 确认调试结果正确。
2. 回到列表，对状态为 草稿 的 API 点击 「发布」。
3. 确认弹窗后，状态变为 已发布。

发布前系统会校验关联数据集仍为已发布；若数据集已下线，需先发布数据集或更换绑定。

8.2 下线

对已发布 API 点击 「下线」，状态回到草稿。下线后外部 HMAC 调用将返回 404（视同 API 不存在），管理端仍可编辑与调试。

8.3 删除

不再需要时可「删除」；删除后不可恢复，外部调用立即失效。

九、生产环境调用（开放 API）

9.1 前置条件

1. 数据服务 API 状态为 已发布。
2. 关联数据集为 已发布。
3. 在 开放平台 → AccessKey 管理 创建密钥（SecretKey 仅展示一次）。
4. 服务端实现 HMAC-SHA256 签名，详见 API 使用说明。

9.2 POST 取数（推荐）

POST /api/open/v1/data-service/{apiName}/query
Authorization: VR-HMAC-SHA256 AccessKeyId=...,Timestamp=...,Nonce=...,Signature=...
Content-Type: application/json

请求体示例（以 apiName=salesman 为例）：

{
  "params": {
    "region": "华东"
  },
  "pagination": {
    "page": 1,
    "pageSize": 20
  }
}

成功响应示例：

{
  "code": 0,
  "data": {
    "total": 100,
    "page": 1,
    "pageSize": 20,
    "rows": [ { "salesman_id": "001", "name": "张三" } ],
    "columns": [ { "name": "salesman_id", "type": "STRING" } ]
  }
}

接口字段说明请参阅 QueryDataService - POST 取数。

9.3 GET 取数

GET /api/open/v1/data-service/salesman/query?region=华东&page=1&pageSize=20
Authorization: VR-HMAC-SHA256 ...

适合参数较少的场景；业务参数与 page、pageSize 一并放在 Query 中。详见 QueryDataServiceGet - GET 取数。

十、安全与约束

• 租户隔离：API 与数据集均绑定租户，不可跨租户访问
• 双发布：API 与数据集都须已发布，任一下线则外部不可用
• 行数上限：受 API 配置的「返回条数」与开放 API 分页参数共同约束
• 统计：已发布 API 的外部调用计入开放平台调用日志（data-service 分组）

十一、常见问题

Q：调试返回空数据？
A：① 确认数据集在数据建模 → 数据预览中有数据；② 返回参数的「绑定字段」与预览列名一致；③ 若配置了请求参数，调试时填写有效值；④ 数据集须为已发布状态。

Q：数据集已下线，调试还能用吗？
A：不能。关联数据集下线后，调试、发布与外部调用均会拦截，需重新发布数据集或更换为其他已发布数据集。

Q：API 已发布但外部调用 404？
A：检查 API 名称拼写、AccessKey 签名、关联数据集是否仍为已发布；草稿状态 API 对外视同不存在。

Q：请求参数里的「操作符」何时生效？
A：仅当数据集为 SQL 节点且 SQL 含 ${参数名} 占位符时，通过参数替换生效；表模型数据集一般留空请求参数即可。

Q：如何查看调用量？
A：开放平台 → 数据服务统计（或开放 API 统计中 data-service 分组），可查看调用趋势与明细。

十二、相关文档

• 开放 API 概述
• API 使用说明（HMAC 签名）
• 数据服务 POST 接口
• 分析集成（报表嵌入）