You need to enable JavaScript to run this app.
导航
Open API 概述
最近更新时间:2024.01.03 14:59:15首次发布时间:2022.10.27 19:45:04
1. 整体流程

(1)为每一个 openapi 调用方生成一个 client id 和 client secret,并且要求每一个 client 绑定一个真实的用户身份(通过申请 client 接口传入的短期身份凭证 sessionid 或者 digest),形成信任链
(2)用户使用 client id / secret 调用接口交换包含用户身份信息的 jwt token
(3)用户在调用业务接口时在请求头部带上 jwt token,例如:  Authorization: Bearer jwt_token
(4)DataWind 在接口被调用时,使用公钥校验 jwt token,完成限流检查、审计
(5)返回业务结果
整体流程如下:
alt

2. Token申请接口

(1)获取登录凭证

访问 DataWind ,正常登陆账号后获取 cookie 中的登录凭证。不同环境登录凭证的 key 可能会不同:

  • 私有化部署版本默认为sessionid
  • 火山引擎 SaaS 版本为digest

具体操作如下:
鼠标右键点击页面——检查,进入浏览器控制台,找到 application 子页面,获取 cookie 中的sessionid或者digest

说明

注意,如果需要申请bindingType为system的账号,需要使用系统管理员账号登录。

(2)使用第一步获取的登录凭证设置在请求的 cookie 中,申请 openapi client

不同环境调用接口使用的接口地址不同:

  • 如果是私有化部署环境,调用接口的使用的地址前缀与私有化环境访问地址一致
  • 如果是火山引擎 SaaS 环境,访问地址为https://console.volcengine.com/bi/datawind,则接口地址前缀为https://console.volcengine.com/bi/datawind/aeolus

申请 client id / secret 的相关接口如下:(同一用户只可以申请不多于3个 openapi client)

注意

务必妥善保密管理clientIdclientSecret,这是调用接口的凭证。

说明

  • 获取 sessionid 与 client id/secret 只需手动操作一次,生成的 client id/secret 不会过期。
  • 请务必不要在代码逻辑中使用固定短期登陆凭证 sessionid/digest 自动申请 client,短期凭证会随登录态失效,后续接口直接使用 client id/secret 申请 token 即可。
# 创建openapi client
POST /aeolus/api/v3/openapi/client?bindingType=user
Cookie: sessionid= 或者 digest=

sessionid: 第一步中获取的sessionid,放在cookie中,下同。
bindingType: 可选参数, user or system,默认值user。
type为system的client只有系统管理员允许申请
此类client可以获取任意用户身份的jwtToken,用于内部服务之间的鉴权。

返回值
{
    "code": "aeolus/ok",
    "data": {
        "bindingType": "user",
        "clientId": xxx,
        "clientSecret": yyy,
        "proxyUser": xiajinfu.xjf,
    }
}

# 获取用户关联的所有openapi client
GET /aeolus/api/v3/openapi/clients
Cookie: sessionid=

返回值
{
    "code": "aeolus/ok",
    "data": ["client_id1", "client_id2"],
}

# 删除用户关联的openapi client
DELETE /aeolus/api/v3/openapi/client?clientId=
Cookie: sessionid=

返回值
{
    "code": "aeolus/ok",
    "data": "",
}
  1. 使用 client id / secret 交换 jwt token
    1. proxyUser,可选参数,默认为client的owner

      1. Binding type 为 user,则该值必须与client的owner一致

      2. Binding type 为 system,则该值可以为任意的用户

    2. expire,可选参数,token过期时间,单位为秒。

      1. 最大的token过期时间为3天
    3. userPayload,可选参数,如果存在,该值会被原样加密到jwt token中

      1. 因为jwt token每次请求都需要带上,所以不建议放过长的内容

      2. 这个参数并不是调用接口时传递的payload,只是用于签发jwt token时的自定义拓展字段。没有特殊需求留空即可。jwt token在失效前都可以复用,没有特殊需要不需要每次调用前重新申请。

POST /aeolus/api/v3/openapi/jwtToken
{
    "metadata": {
        "clientId": xxx,
        "clientSecret": yyy,
        "proxyUser": "xiajinfu.xjf",
        "expire": 3600
    },
    "userPayload": {
        "somekey": "somevalue"
    }
}

返回值
{
    "code": "aeolus/ok",
    "data": {
        "jwtToken": xxxx,
    }
}

Jwt token的payload结构定义如下:

{
    "token_type": "openapi",
    "client_id": xxx,
    "username": "xiajinfu.xjf",
    "exp": 1371720939, // jwt标准定义的过期时间格式
    "user_payload": {
        "somekey": "somevalue"
    }
}

(3)业务方调用接口时,在请求头部带上 jwt token,例如:Authorization: Bearer jwt_token

使用 curl 的调用 current user 接口示例如下:

curl -X GET 'https://{domain}/aeolus/api/v3/open/misc/current_user' \
-H 'Authorization: Bearer jwt_token'

(4)如果需要验证和解密 jwt token 的完整性(一般业务方不需要,只用把 token 原样回传给 DataWind 即可),可获取 pubkey(可缓存),接口如下:

GET /aeolus/api/v3/openapi/publicKey
无鉴权

返回值
{
    "code": "aeolus/ok",
    "data": {
        "publicKey": ""
    }
}

(5)使用 curl 的一些命令示例:

申请 client id / secret:

curl -XPOST 'http://{domain}/aeolus/api/v3/openapi/client?bindingType=user' \
-H 'Cookie: sessionid='

返回值:
{
  "code": "aeolus/ok",
  "data": {
    "bindingType": "user",
    "clientId": "xxx",
    "clientSecret": "yyy",
    "ownerEmailPrefix": "user_1"
  },
  "msg": "成功"
}

生成jwt token:

curl -XPOST 'http://{domain}/aeolus/api/v3/openapi/jwtToken' \
-H 'Content-Type: application/json' \
--data-binary \
'{
    "metadata":{
        "clientId":"xxx",
        "clientSecret":"yyy",
        "expire":3600,
        "proxyUser":"user_1"
    }
}'

返回值:
{
  "code": "aeolus/ok",
  "data": {
    "jwtToken": "token.example",
    "proxyUser": "user_1"
  },
  "msg": "成功"
}

使用 token 调用业务接口

curl -X GET 'http://{domain}/aeolus/api/v3/open/misc/current_user' \
-H 'Authorization: Bearer token.example'
3. 接口调用限制

为了保障服务稳定性与阻挡恶意攻击,DataWind 后端采用以下方法限制请求:

(1)限流(QPS 2000,可申请修改)

(2)封禁,用于保留一些不开放的 api 或者临时封禁用户的异常请求。

(3)审计,每一次 openapi 调用均会被记录,包括调用方、接口、参数、调用时间

4. 相关错误码

错误码以返回结果中的code字段为准,msg字段不保证不会做变动:

(1)token过期

{
  "code": "aeolus/openapiClient/tokenExpired",
  "extra_msg": {},
  "msg": "token已过期",
  "queryHistoryId": 0
}

(2)token 错误

{
  "code": "aeolus/openapiClient/tokenError",
  "extra_msg": {},
  "msg": "token不正确",
  "queryHistoryId": 0
}

(3)token 调用超过频率限制

{
  "code": "aeolus/openapiClient/requestRateExcess",
  "extra_msg": {},
  "msg": "请求频率超限",
  "queryHistoryId": 0
}

(4)token 被禁用

{
  "code": "aeolus/openapiClient/blocked",
  "extra_msg": {},
  "msg": "请求已被拦截",
  "queryHistoryId": 0
}