Open API 概述

（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）返回业务结果
整体流程如下：

（1）获取登录凭证

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

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

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

（2）使用第一步获取的登录凭证设置在请求的 cookie 中，申请 openapi client

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

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

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

# 创建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": "",
}

3. 使用 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'

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

（1）限流（QPS 2000，可申请修改）

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

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

错误码以返回结果中的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
}