TEM OpenAPI 简介

为了方便TEM 用户使用API 来对 TiDB 集群进行管理和开发自己的应用程序，TEM 提供了REST 风格的 OpenAPI。本文档详细介绍了 TEM 提供的API 的描述、语法和示例。

OpenAPI 调用说明

本文会介绍如何使用 HTTP 方式调用 TEM 的 OpenAPI。

完整的 HTTP 请求通常需要包含请求的URL，方法，消息头和消息体。其中：

URL：代表了需要访问的资源的唯一地址，例如： http://127.0.0.1:8080/api/v1/resource/monitor?ip=172.17.0.15

在上面的地址中：http 代表了数据传输的协议，127.0.0.1:8080 代表了 TEM 服务所在的地址，/api/v1/resource/monitor 代表了需要访问的资源的路径，ip=172.17.0.15 则表示了查询的参数。

方法：因为 TEM 提供的 OpenAPI 是符合 REST 规范的，提供了 GET、PUT、POST、DELETE 方法。
消息头：则是每次请求的时候都会携带的一些附加信息，包含了消息体的类型和鉴权信息。目前 TEM 的消息体仅支持application/json 类型。对于鉴权信息，目前 TEM 使用了基于的Token 鉴权方式，其格式为TEM-AUTH:{accesskey}:{signature}:{unixtime}。每个用户的accesskey 和 secretkey 可以在用户管理相关的功能中进行配置。具体内容可以参考 TEM 用户使用指南
消息体代表了调用 OpenAPI 时需要发送给 TEM 的业务数据，目前仅支持json 格式的消息体。

鉴权逻辑说明

TEM 使用了基于AK/SK签名认证方式来对接收到的OpenAPI请求进行鉴权，下面的内容详细介绍了鉴权流程与实现逻辑。

签名信息通过Header携带，算法则决定了使用哪种算法来生成签名。

算法

算法名称遵循以下规则L{级别}.{摘要算法}
为了方便使用，前端只提供L0.PAINTEXT,L3.SHA256两种算法选项。

可选算法

L0.PAINTEXT 实现简单，使用明文信息，无需动态计算。建议只用于测试。
L0.SHA1 安全性提高一些，将秘钥信息做SHA1签名。建议只用于测试。
L3.SHA1 将请求信息以及时间信息做SHA1签名，可抵御重放攻击，安全性较高。
L3.SHA256 将请求信息以及时间信息做SHA1签名，可抵御重放攻击，安全性最高。

签名样式

// L3 级别规范
Authorization Bearer TEM-AUTH:{accesskey}:{signature}:{unixtime}
// L0 级别规范
Authorization Bearer TEM-AUTH:{accesskey}:{signature}

信息

算法: 使用hash算法签名，算法配置在AKSK中。
AK(Access Key): 用户访问ID。
SK(Secret Key): 鉴权秘钥，存放在数据库和用户手中。
UnixTime: 请求的时间，UnixTime，精确到秒。
Method: 请求方式,大写。POST,GET。
URL: 请求的路径。
Params: 请求参数
- POST,PUT 等，直接使用body字符串。
- GET/DELETE 等，参数直接在URL中，留空即可。必须指定使用的签名算法。

示例

L0.* 签名逻辑

假设

accessKey: pingcap
secretKey: pingcap

L0.PAINTEXT

// TEM-AUTH:{accessKey}:{secretKey}
TEM-AUTH:pingcap:pingcap

L0.SHA1

// TEM-AUTH:{accessKey}:SHA1({secretKey})
TEM-AUTH:pingcap:73bf9ef43a44f42e2ea2894d62f0917af149a006

L3.SHA* 签名逻辑

将信息组合成的字符串，分隔符用 '|'，再计算摘要信息。如果是GET，为空，如果是POST,就是Json字符串。

ak:<AK>|sk:<SK>|time:<UnixTime>|method:<Method>|url:<URL>|params:<Params>

和其它必要信息组合成Token，放到 Header 上。

Authorization Bearer TEM-AUTH:{accesskey}:{signature}:{unixtime}

示例脚本 L3.SHA256

// 获取 query 参数 param1, param2
var querybody = request.request_bodys;

function GetUrlRelativePath(url) {
    var arrUrl = url.split("//");

    var start = arrUrl[1].indexOf("/");
    var relUrl = arrUrl[1].substring(start);
    return relUrl;
}

// 获取URL
var urlstr = GetUrlRelativePath(request.url)
var method = request.method

console.log(request)

// 获取预先设置为环境变量的 accessKey 和 secretKey
var ak = apt.variables.get("accessKey");
var sk = apt.variables.get("secretKey");

var timestamp = parseInt(new Date().getTime() / 1000);

var painttext = "ak:" + ak + "|sk:" + sk + "|time:" + timestamp + "|method:" + method + "|url:" + urlstr + "|params:" + querybody
console.log(painttext);

// 将 str 进行 sha256 加密生成 sign
var sign = CryptoJS.SHA256(painttext).toString();

var token = "TEM-AUTH:" + ak + ":" + sign + ":" + timestamp
apt.setRequestHeader("Authorization", "Bearer " + token);
console.log(token);

OpenAPI 调用示例

下面以查看某一个 TiDB 集群的详细信息为例，演示如何调用 TEM的 OpenAPI。

首先，使用cluster_manager 用户登陆到 TEM 并点击屏幕右上角的用户头像，进入到用设置页面。在用户设置页面的密钥管理部分使用加密算法“L0.PLAINTEXT”生成一个新的密钥。

之后，运行下面的curl命令调用 TEM 的 OpenAPI 来查询一个集群的详细信息。

curl -X GET -H "Authorization: Bearer TEM-AUTH:5e685006656cfc80:75997c30879a58436fa55d73c7b9c5c9" http://172.16.6.62:8080/api/v1/cluster/tidbs/tidb-e6fbbdd6f4b0affc

以上的命令会返回类似与以下的输出

{
    "Data": {
        "Abstract": {
            "ComponentSize": {
                "alertManager": 1,
                "grafana": 1,
                "monitor": 1,
                "pd": 1,
                "tidb": 1,
                "tiflash": 1,
                "tikv": 1
            },
            "Resource": {
                "CPU": 14,
                "Memory": 14
            }
        },
        "AccessEntrys": {
            "DB": {
                "Description": "tidb Access address",
                "Host": "172.17.0.13",
                "Port": 4000,
                "Type": "mysql",
                "UseFor": ""
            },
            "Dashboard": {
                "Description": "tidb dashboard",
                "Host": "172.17.0.13",
                "Port": 2379,
                "Type": "http",
                "UseFor": ""
            }
        },
        "Alias": "tidb-4ef6d213f0d03263",
    ......
    "Success": true
    }

TEM OpenAPI简介