嵌出链接加密使用流程--智能数据洞察-火山引擎

文档中心

立即注册

导航

嵌出链接加密使用流程

最近更新时间：2024.11.20 19:12:05首次发布时间：2023.12.12 14:41:44

1. 概述

本产品的私有化部署版本支持将图表或仪表盘的嵌出链接加密成短链。用户可通过 OpenAPI 对加密链接进行增删改查，以及应用等操作。下文将为您具体介绍。
注意：在您使用本文所述的接口前，请先了解调用方式，详情可阅读调用方式。

2. OPEN API对加密链接进行增删改查

2.1 JWT Token申请

以系统管理员(不是项目管理员)身份登录 DataWind，获取 cookie 中的sessionid，具体操作如下：
鼠标右键点击页面——检查，进入浏览器控制台，找到 application 子页面，获取 cookie 中的sessionid。

POST /aeolus/api/v3/openapi/client?bindingType=system
# sessionid: 第一步中获取的sessionid，放在cookie中，下同。
Cookie: sessionid=xxx

返回示例
{
    "code": "aeolus/ok",
    "data": {
        "bindingType": "system",
        "clientId": "xxx",
        "clientSecret": "yyy",
        "ownerEmailPrefix": "系统管理员用户名",
    }
}

务必妥善保密管理clientId与clientSecret，这是调用接口的凭证。
获取sessionid与client id/secret只需手动操作一次，生成的client id/secret不会过期。
请务必不要在代码逻辑中使用固定sessionid自动申请client，sessionid会随登录态失效，后续接口直接使用client id/secret 申请token即可。
拿到clientId与clientSecret生成JWT Token：

POST /aeolus/api/v3/openapi/jwtToken
{
    "metadata": {
        "clientId": "xxx",
        "clientSecret": "yyy",
        "proxyUser": "系统管理员用户名",
        "expire": 3600  // token过期时间，单位为秒，最大的token过期时间为3天
    }
}

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

详情参考：【对外】DataWind OpenAPI 用户手册

2.2 生成短链接

POST /aeolus/api/v3/open/embedUrl/shortUrl HTTP/1.1
# header请求参数
Content-Type: application/json
Authorization: Bearer {jwt-token}
# body请求参数
{
    # 完整链接地址
    "fullUrl": "https://xxx.com/#/dashboard/123?appId=456",
    # 允许访问的网段，不能为空或者空数组
    "zone": ["z1", "z2"],
    # 描述信息
    "descr": "xxxx"
}

返回值
{
    "code": "aeolus/ok",
    "data": {
        # 短链接唯一id
        "id": 6,
        # 短链接
        "shortUrl": "pgJJ96KV9N91NtosFd5AXViWr1CKf4d4"
    },
    "msg": "成功"
}
# 请求失败的情况
# 当code不为"aeolus/ok"，请求就认为失败
{
    "code": "aeolus/embed/domainAdminOnly",
    "extra_msg": {},
    "msg": "只有系统管理员才能访问",
    "queryHistoryId": 0
}
{
    "code": "aeolus/embed/embedUrlMustHasParam",
    "extra_msg": {},
    "msg": "嵌出链接需要包含xxx=xxx形式的配置参数",
    "queryHistoryId": 0
}
{
    "code": "aeolus/embed/embedUrlOnlySupportDashboardOrReport",
    "extra_msg": {},
    "msg": "嵌出链接只支持仪表盘或仪表盘中的图表",
    "queryHistoryId": 0
}
{
    "code": "aeolus/openapiClient/tokenExpired",
    "extra_msg": {},
    "msg": "token已过期",
    "queryHistoryId": 0
}
{
    "code": "aeolus/parameter/absent",
    "extra_msg": {
        "params": "fullUrl"
    },
    "msg": "缺少必要参数",
    "queryHistoryId": 0
}

2.3 修改短链接配置

PATCH /aeolus/api/v3/open/embedUrl/shortUrl HTTP/1.1
# header请求参数
Content-Type: application/json
Authorization: Bearer {jwt-token}
# body请求参数
{
    # 短链接唯一id
    "id": 1,
    # 短链接
    "shortUrl": "DPnPSuSPYwnf5tLqGoO19HM48UAuri4h",
    # 以上参数至少有一个，如果两个都传，需要保证能匹配上，否则无法更新
    
    # 完整url
    "fullUrl": "https://xxx.com/#/dashboard/123?appId=789",
    # 允许访问的网段
    "zone": ["z3"],
    # 描述信息
    "descr": "新的描述"
}

# 返回值
{
    "code": "aeolus/ok",
    "data": {},
    "msg": "成功"
}
# 请求失败的情况
# 当code不为"aeolus/ok"，请求就认为失败
{
    "code": "aeolus/embed/notFound",
    "extra_msg": {},
    "msg": "短连接不存在或已被删除",
    "queryHistoryId": 0
}
{
    "code": "aeolus/parameter/absent",
    "extra_msg": {
        "params": "id"
    },
    "msg": "缺少必要参数",
    "queryHistoryId": 0
}
{
    "code": "aeolus/openapiClient/tokenExpired",
    "extra_msg": {},
    "msg": "token已过期",
    "queryHistoryId": 0
}
{
    "code": "aeolus/embed/embedUrlMustHasParam",
    "extra_msg": {},
    "msg": "嵌出链接需要包含xxx=xxx形式的配置参数",
    "queryHistoryId": 0
}
{
    "code": "aeolus/embed/embedUrlOnlySupportDashboardOrReport",
    "extra_msg": {},
    "msg": "嵌出链接只支持仪表盘或仪表盘中的图表",
    "queryHistoryId": 0
}
{
    "code": "aeolus/embed/domainAdminOnly",
    "extra_msg": {},
    "msg": "只有系统管理员才能访问",
    "queryHistoryId": 0
}

2.4 失效短连接

PATCH /aeolus/api/v3/open/embedUrl/disableShortUrl HTTP/1.1
# header请求参数
Content-Type: application/json
Authorization: Bearer {jwt-token}

# body请求参数
{
    # 短链接唯一id
    "id": 1,
    # 短链接
    "shortUrl": "DPnPSuSPYwnf5tLqGoO19HM48UAuri4h",
    # 以上参数至少有一个，如果两个都传，需要保证能匹配上，否则无法更新
}
# 返回值
{
    "code": "aeolus/ok",
    "data": {},
    "msg": "成功"
}
# 请求失败的情况
# 当code不为"aeolus/ok"，请求就认为失败
{
    "code": "aeolus/embed/domainAdminOnly",
    "extra_msg": {},
    "msg": "只有系统管理员才能访问",
    "queryHistoryId": 0
}
{
    "code": "aeolus/openapiClient/tokenExpired",
    "extra_msg": {},
    "msg": "token已过期",
    "queryHistoryId": 0
}
{
    "code": "aeolus/embed/notFound",
    "extra_msg": {},
    "msg": "短连接不存在或已被删除",
    "queryHistoryId": 0
}

2.5 生效短连接

PATCH /aeolus/api/v3/open/embedUrl/enableShortUrl HTTP/1.1
# header请求参数
Content-Type: application/json
Authorization: Bearer {jwt-token}

# body请求参数
{
    # 短链接唯一id
    "id": 1,
    # 短链接
    "shortUrl": "DPnPSuSPYwnf5tLqGoO19HM48UAuri4h",
    # 以上参数至少有一个，如果两个都传，需要保证能匹配上，否则无法更新
}
# 返回值
{
    "code": "aeolus/ok",
    "data": {},
    "msg": "成功"
}
# 请求失败的情况
# 当code不为"aeolus/ok"，请求就认为失败
{
    "code": "aeolus/embed/domainAdminOnly",
    "extra_msg": {},
    "msg": "只有系统管理员才能访问",
    "queryHistoryId": 0
}
{
    "code": "aeolus/openapiClient/tokenExpired",
    "extra_msg": {},
    "msg": "token已过期",
    "queryHistoryId": 0
}
{
    "code": "aeolus/embed/notFound",
    "extra_msg": {},
    "msg": "短连接不存在或已被删除",
    "queryHistoryId": 0
}

2.6 删除短连接

DELETE /aeolus/api/v3/open/embedUrl/shortUrl HTTP/1.1
# header请求参数
Content-Type: application/json
Authorization: Bearer {jwt-token}

# body请求参数
{
    # 短链接唯一id
    "id": 1,
    # 短链接
    "shortUrl": "DPnPSuSPYwnf5tLqGoO19HM48UAuri4h",
    # 以上参数至少有一个，如果两个都传，需要保证能匹配上，否则无法更新
}
# 返回值
{
    "code": "aeolus/ok",
    "data": {},
    "msg": "成功"
}
# 请求失败的情况
# 当code不为"aeolus/ok"，请求就认为失败
{
    "code": "aeolus/embed/domainAdminOnly",
    "extra_msg": {},
    "msg": "只有系统管理员才能访问",
    "queryHistoryId": 0
}
{
    "code": "aeolus/openapiClient/tokenExpired",
    "extra_msg": {},
    "msg": "token已过期",
    "queryHistoryId": 0
}
{
    "code": "aeolus/embed/notFound",
    "extra_msg": {},
    "msg": "短连接不存在或已被删除",
    "queryHistoryId": 0
}

2.7 获取所有短链接

GET /aeolus/api/v3/open/embedUrl/shortUrlList HTTP/1.1
# header请求参数
Authorization: Bearer {jwt-token}

# 返回值
{
    "code": "aeolus/ok",
    "data": [
        {
            # 创建时间
            "ctime": "2023-07-21 16:38:00",
            # 描述
            "descr": "11111",
            # 完整链接
            "fullUrl": "https://xxx.com/#/external/dashboard/123?inline=true&appId=1&sheetId=2&feature=%7B%22dashboard%22%3A%7B%22showTitle%22%3Afalse%2C%22showOwner%22%3Afalse%2C%22showActions%22%3Afalse%2C%22sheetType%22%3A%22all%22%2C%22sheetList%22%3A%5B%5D%2C%22showHeader%22%3Afalse%2C%22showFavor%22%3Afalse%2C%22actions%22%3A%5B%5D%2C%22report%22%3A%7B%22showTitle%22%3Afalse%2C%22showTips%22%3Afalse%2C%22showToolbar%22%3Afalse%2C%22showHeader%22%3Afalse%7D%2C%22sheet%22%3A%7B%7D%7D%7D",
            # 唯一id
            "id": 3,
            # 最近一次修改时间
            "mtime": "2023-07-21 16:38:12",
            # 短链接
            "shortUrl": "TsouUsnzx0iOCxacDxpldJ6OfshLKPZf",
            # 链接状态，0：启用，1：失效
            "status": 0,
            # 生效网段
            "zone": ["z1"， "z2"]
        },
        {
            "ctime": "2023-07-21 18:06:32",
            "descr": "22222",
            "fullUrl": "https://xxx.com/#/external/dashboard/123/456?inline=true&appId=1&sheetId=2&feature=%7B%22dashboard%22%3A%7B%22report%22%3A%7B%22showTitle%22%3Afalse%2C%22showTips%22%3Afalse%2C%22showToolbar%22%3Afalse%2C%22showHeader%22%3Afalse%7D%7D%7D",,
            "id": 5,
            "mtime": "2023-07-21 18:47:21",
            "shortUrl": "DPnPSuSPYwnf5tLqGoO19HM48UAuri4h",
            "status": 1,
            "zone": ["z3"]
        }
    ],
    "msg": "成功"
}
# 请求失败的情况
# 当code不为"aeolus/ok"，请求就认为失败
{
    "code": "aeolus/embed/domainAdminOnly",
    "extra_msg": {},
    "msg": "只有系统管理员才能访问",
    "queryHistoryId": 0
}

3. 对加密链接进行嵌出应用

因为存在客户设置了多网络区，因此不同的网络区的域名不一致，为了便于多处使用。
域名部分不参与短链的生成。

3.1 应用步骤

第一步，确定嵌出链接。
示例：

域名1：https://www.z1.com/#/dashboard/external/123?appId=456
域名2：https://www.z2.com/#/dashboard/external/123?appId=456

第二步，获取短链：利用Open api 对完整嵌出链接生成加密短链。见文档上步骤。
示例：

域名1返回的短链：pgJJ96KV9N91NtosFd5AXViWr1CKf4d4
域名1返回的短链：DPnPSuSPYwnf5tLqGoO19HM48UAuri4h

第三步，拼接加密可访问的链接：“域名”+“#/share/” +“短链”
示例：

域名1：https://www.z1.com/#/share/pgJJ96KV9N91NtosFd5AXViWr1CKf4d4
域名2：https://www.z2.com/#/share/DPnPSuSPYwnf5tLqGoO19HM48UAuri4h

3.2 效果对比

加密前的链接	加密后的链接
https://www.z1.com/#/dashboard/external/123?appId=456	https://www.z1.com/#/share/pgJJ96KV9N91NtosFd5AXViWr1CKf4d4