VeryReport · 帮助文档

API使用说明

1. 概述

开放 API 使用 AccessKey + SecretKey 进行 HMAC 签名认证。SecretKey 仅在创建时展示一次，请妥善保存；所有签名计算应在服务端完成，切勿将 SecretKey 暴露给浏览器或移动端。

2. 准备工作

2.1 创建 AccessKey

使用管理员账号登录 VeryReport。
进入菜单 开放平台 → 开放 API。
在「AccessKey 凭证」区域点击「新建」，填写名称与权限范围（READ_ONLY 或 FULL）。
创建成功后立即复制 AccessKeyId 与 SecretKey；关闭弹窗后 SecretKey 不可再次查看。

2.2 确认开放 API 已启用

部署环境需配置 apollo.open-platform.open-api.enabled=true（默认开启）。若设为 false，所有 /api/open/v1/** 请求将返回 503。

3. 构造签名

3.1 Authorization 请求头

Authorization: VR-HMAC-SHA256 AccessKeyId={AccessKeyId},Timestamp={毫秒时间戳},Nonce={随机字符串},Signature={签名}

3.2 StringToSign

StringToSign = METHOD + "\n"
             + PATH + "\n"
             + Timestamp + "\n"
             + Nonce + "\n"
             + SHA256_HEX(RequestBody)

METHOD：HTTP 方法，如 GET、POST
PATH：请求路径（不含域名与 Query），如 /api/open/v1/users
Timestamp：毫秒时间戳，与服务端误差不超过 ±5 分钟
Nonce：随机字符串，用于防重放
RequestBody：GET 请求为空字符串；POST/PUT 为原始 JSON 正文

3.3 计算 Signature

Signature = Base64( HMAC-SHA256( StringToSign, SecretKey ) )

注意：Signature 为 Base64 编码；请求体哈希为 SHA256 十六进制小写。

4. 发起请求示例

以查询用户列表为例：

GET /api/open/v1/users?page=1&pageSize=20 HTTP/1.1
Host: your-apollo-host
Authorization: VR-HMAC-SHA256 AccessKeyId=VR_AK_xxx,Timestamp=1710000000000,Nonce=abc123,Signature=...

5. 权限说明

参数名	类型	必填	说明
`READ_ONLY`	string	-	允许所有读接口；写接口（创建用户、刷新数据集等）返回 40301
`FULL`	string	-	允许读与写接口

6. 常见问题

401 认证失败：检查 Timestamp 是否在有效期内、PATH 是否与签名一致、Signature 是否为 Base64。
404 资源不存在：作品/数据集可能未发布，或 ID 不属于当前租户。
403 无权限：READ_ONLY 的 Key 调用了写接口，请更换 FULL 权限 Key。

接口明细请参阅开放 API 概述中的接口目录。