调用方式--智能数据洞察-火山引擎

文档中心

导航

调用方式

最近更新时间：2024.11.20 18:39:31首次发布时间：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）在调用任意一个 DataWind 接口时，为了便于后续问题的排查，建议在请求的 headers 中添加 x-request-id 和 request-id(保证唯一字符串即可)。这两个参数会被输入到 DataWind 的后端日志中，为您在遇到问题时进行分析和定位提供有力的支持，从而更高效地解决可能出现的故障。
（6）返回业务结果
整体流程如下：

2. 请求结构与返回结构

（1）获取登录凭证

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

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

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

说明

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

（2）申请 openapi client

使用第一步获取的登录凭证设置在请求的 cookie 中，申请 openapi client
不同环境调用接口使用的接口地址不同：

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

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

注意

务必妥善保密管理clientId与clientSecret，这是调用接口的凭证。

说明

获取 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": "",
}

（3）使用 client id / secret 交换 jwt token（公共参数）

proxyUser，可选参数，默认为client的owner
1. Binding type 为 user，则该值必须与client的owner一致
2. Binding type 为 system，则该值可以为任意的用户
expire，可选参数，token过期时间，单位为秒。
1. 最大的token过期时间为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"
    }
}

（4）业务方调用接口时，在请求头部带上 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'

（5）验证和解密 jwt token 的完整性

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

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

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

（6）使用 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. 公共错误码

详情可查看《公共错误码》。