search
API DataWay API

DataWay API 说明文档

最近更新时间:2020/06/03

概述

DataWay API 允许具有开发能力的团队或企业通过请求 DataWay 路由上报自定义的数据,从而满足企业数据采集定制化的需求。

约定

字符编码

调用API请求中使用到的参数和返回结果中的字符编码都为 UTF-8

请求协议

HTTP 1.1

访问控制

DataWay 支持多路由,具体可参考 DataWay 多路由配置,默认情况下 DataWay 的路由请求无访问控制(如果请求的路由无访问控制,可直接跳过访问控制阅读文档后面的内容),用户可以配置 ak_open: true 开启路由的访问控制,配置好后重启 DataWay 即可生效。

一旦路由开启了访问控制,在请求 DataWay 路由时则需要通过 DataWay 颁发的 Access KeySecret Key 进行签名认证 ,认证步骤:

步骤一:在 DataWay 的配置文件 dataway.yaml 中获取 Access KeySecret Key

步骤二:计算签名 Signature,算法:

Signature = base64(hmac-sha1(SecretKey,
            Method + "\n"
            + Content-MD5 + "\n"
            + Content-Type + "\n"
            + Date))

  • Secret Key 即 DataWay 颁发的私钥 Secret Key

  • Method 表示HTTP请求的方法,例如 PUT、GET、POST 等。

  • \n 表示换行符。

  • Content-MD5 表示对请求内容(body)进行 MD5 后的值,首先对请求内容(不包括头部)计算 MD5 值获得 128 比特位数字,然后对该数字进行 base64 编码后得出

先计算MD5加密的二进制数组(128位); 对这个二进制数组进行 base64 编码(而不是对32位字符串编码)。

  • Content-Type 表示请求内容的类型,例如 text/plain

  • Date 表示此次操作的时间,且必须为HTTP1.1 规定的GMT时间,格式为[RFC1123](csgnetwork.com/timerfc1123calc.html)。例如 Wed, 20 Nov 2019 09:56:06 GMT

注意,日期的格式为:date1 = 2DIGIT SP month SP 4DIGIT; day month year (e.g., 02 Jun 1982); 在日期格式中,“天”所占位数都是“2 DIGIT”,因此,“Jun 2”、“2 Jun 1982”和“2-Jun-1982”都是非法日期格式, 如果请求中的 Date 时间和 Dataway 服务器的当前时间差15分钟以上,Dataway 服务器将拒绝该请求并发挥错误,详情见下方“错误处理”

  • 以上所有参数皆不能为空

步骤三:生成 Authorization Code:

Authorization = "DWAY " + AccessKey + ":" + Signature
  • "DWAY ",字母后面带一个空格

  • AccessKey 即 DataWay 颁发的公钥 Access Key

步骤四:在请求的 HTTP 头上增加 Authorization 头,值为上一步生成的 Authorization Code

认证错误处理

  • 若用户请求头中 Authorization 值的格式不对,返回 400 Bad Request。错误信息:invalid argument

  • 如果签名验证的时候,头中没有传入Date或者格式不正确,返回403 Forbidden。错误信息:access denied of date

  • 传入请求的时间必须在 DataWay 服务器当前时间前后的15分钟以内,否则返回403 Forbidden。错误信息:request time too skewed

  • 如果接收到的 Authorzation 值与服务器计算所得不匹配,返回400 Bad Request。错误信息:invalid argument

数据写入接口

通用 HTTP Header 请求头参数

以下参数在所有的 DataWay 数据写入接口的 HTTP Header 都支持,可根据实际情况决定是否传入参数

参数 描述 类型 required? 默认值
X-Precision 指定数据的时间精度(n/ns/u/ms/s/m/h),假定采集器获取的时间精度是非纳秒级别(nns),那么就需要通过该参数指定对应的精度,不然 DataWay 无法将无精度的时间转成纳秒 str No n(即纳秒)
X-Token 指定数据的目标工作空间的 token往 OpenWay 打数据必须指定 X-Token,另外,如果通过 OpenWay 往系统工作空间打数据,可以用保留的 __internal__ 作为 token 参数 str No
X-Datakit-UUID 指定数据采集器的 ID,可作为采集器的名称 str No 不指定则以采集器 IP 作为 ID(容易混淆)
X-Version 指定数据采集器版本信息 str No 可以为空
X-Max-POST-Interval 指定当前数据采集器最大的采集间隔,用户检测该数据采集器多久未上报数据标记为失联,如 30s(30秒), 1d(一天) 等 str No 可以为空

上报指标数据 | /v1/write/metrics | POST

  • 接口描述:调用该接口上报指标数据到 DataFlux 中

  • Content-Type: text/plain

  • 请求的 Body 格式为 line protocol,支持同时上报多个数据点,一行表示一个数据点

line protocol 格式说明:

weather,location=us-midwest temperature=82 1465839830100400200
    |   `-----------------' `------------'          |
    |           |                 |                 |
    |           |                 |                 |
+------+------------------+-+------------+-+---------------+
|指标集|, 标签列表        | | 指标列表   | |      时间戳   |
+------+------------------+-+------------+-+---------------+

请求数据说明

参数 参数值 必需 说明
指标集 自定义 当前数据点所属的指标集,字符串类型,用户自定义
标签 自定义 当前数据点的标签,可设置多个标签,多个标签用英文逗号分隔,标签名和标签值都只能是字符串
指标 自定义 当前数据点的指标,可设置多个指标,多个指标用英文逗号分隔,指标名为字符串类型,指标值支持 4 种数据类型,具体参考下面的说明
时间戳 根据实际情况生成 当前数据点产生的时间,纳秒为单位

指标值数据类型:

指标值支持 4 种数据类型:

类型 说明
float 浮点型 默认情况下,所有数值类型的指标值都认为是 float 类型数据
int 整数 如果需要指定指标值为整数,则需要在指标值后面附加 i 标记:例如: temperature=81i,支持的整数范围为:-90233720368547758089023372036854775807
string 字符串 如果需要指定指标值为字符串,则需要将指标值通过双引号括起来:例如:temperature="too warm",字符串最大支持 64KB 大小
boolean 布尔类型 可设定指标值为 t T true True TRUE 代表 TRUE,设定指标值为 f F false False FALSE 代表 FLASE,例如: too_hot=true

指定指标数据保留时长

通过在 HTTP Header 增加 X-RP 头可指定当前数据在 DataFlux 中保留的时长,可选参数值:

参数值 说明
rp6 数据保留 25920h即 3 年
rp5 数据保留 8640h即 1 年
rp4 数据保留 4320h即 6 个月
rp3 数据保留 2160h即 3 个月
rp2 数据保留 720h即 1 个月
rp1 数据保留 168h即 1 周
rp0 数据保留 24h即 1 天

如果不指定 X-RP 参数,则系统自动将数据存入默认 RP 上,该默认 RP 是系统初始化即指定好的,每个部署可能不同。一般情况下,不需要指定该参数。

请求示例

POST / HTTP/1.1
Host: {{dataway_route}}
X-Datakit-UUID: {{datakit_uuid}}
Content-Type: text/plain

weather,location=上海,country=中国 temperature_str="hot",temperature=32 1579067200000000000
weather,location=杭州,country=中国 temperature_str="cold",temperature=18 1579067200000000000
weather,location=武汉,country=中国 temperature_str="hot",temperature=30.5 1579067200000000000

上报日志数据 | /v1/write/logging | POST

  • 接口描述:调用该接口上报日志数据到 DataFlux 中

  • Content-Type: text/plain

  • 请求的 Body 格式为 line protocol,支持同时上报多个数据点,一行表示一条日志

请求数据说明

参数 参数值 必需 说明
指标集 [source] 指定当前日志的来源,比如如果来源于 Ngnix,可指定为 Nginx,同一应用产生的日志 source 应该一样,这样在 DataFlux 中方便针对该来源的日志配置同一的提取规则
标签 - 日志数据有保留标签
指标 - 日志数据有保留的指标
时间戳 - 当前日志发生的时间,默认单位为纳秒

保留标签

标签名 是否必需 说明
__class 日志的子分类,目前仅支持:tracing:表示该日志是链路追踪日志
__source 日志来源,日志上报后,会自动将指定的指标集名作为该标签附加到该条日志上

保留指标

指标名 是否必需 类型 说明
__content string 日志内容,纯文本或 JSONString 都可以

上报链路数据 | /v1/write/tracing | POST

  • 接口描述:调用该接口上报链路数据到 DataFlux 中

  • Content-Type: text/plain

  • 请求的 Body 格式为 line protocol,支持同时上报多个数据点,一行表示一条日志

请求数据说明

参数 参数值 必需 说明
指标集 [source] 指定当前链路数据的来源,比如如果来源于 zipkin,可指定为 zipkin,同一链路框架数据 source 应该一样,这样在 DataFlux 中方便针对该来源的链路配置同一的提取规则
标签 - 链路数据有保留标签
指标 - 链路数据有保留的指标
时间戳 - 当前链路发生的时间,默认单位为纳秒

保留标签

标签名 是否必需 说明
__serviceName 服务的名称,建议用户通过该标签指定产生该日志业务系统的名称
__parentID 表示当前 span 的上一个 span的 ID
__operationName 表示当前 span 操作名,也可理解为 span 名称
__spanID 表示当前 span 的 ID
__traceID 表示当前链路的 ID
__isError 字符串类型,true 表示该 span 的请求响应是错误,false 或者无该标签,表示该 span 的响应是正常的请求
__spanType span 的类型,目前支持 2 个值:entrylocalentry span 表示该 span 的调用的是服务的入口,即该服务的对其他服务提供调用请求的端点,几乎所有服务和消息队列消费者都是 entry span,因此只有 span 是 entry 类型的调用才是一个独立的请求。 local span 表示该 span 和远程调用没有任何关系,只是程序内部的函数调用,例如一个普通的 Java 方法,默认值 entry
__endpoint 请求的目标地址,客户端用于访问目标服务的网络地址(但不一定是 IP + 端口),例如 127.0.0.1:8080 ,默认:null

保留指标

指标名 是否必需 类型 说明
__content string 链路数据内容,JSONString
__duration int 当前链路的请求响应时间,微秒为单位

上报事件数据 | /v1/write/keyevent | POST

  • 接口描述:调用该接口上报事件数据到 DataFlux 中

  • Content-Type: text/plain

  • 请求的 Body 格式为 line protocol,支持同时上报多个数据点,一行表示一个事件

请求数据说明

参数 参数值 中文名 必需 说明
指标集 __keyevent 事件 上报关键事件指标集指定为 __keyevent
标签 - - 事件包含保留标签
指标 - - 事件包含保留的字段
时间戳 - - 当前事件发生的时间,时间戳,默认单位为纳秒

保留标签

标签名 中文名 必需 说明
__status(原名 $level) 状态 事件等级和状态,只能是 info:提示,warning:警告,error:错误,critical:严重,ok:恢复
__eventId 事件ID __eventID 如果相同, 系统默认会认为是相关数据,如果 __eventId 为空,系统会自动计算出一个 __eventId,算法参考下面的说明
__source 来源 事件的来源,保留值 datafluxTrigger 表示来自触发器
__ruleId 触发规则ID 触发器对应的触发规则id
__ruleName 触发规则名 触发器对应的触发规则名
__type 事件类型 保留值 noData 表示无数据告警
[触发对象的tagkey] 触发对象 当成自定义标签写入,如果与用户输入的自定义标签名冲突,覆盖用户输入的自定义标签名
__actionType 触发动作类型 触发动作
[自定义标签] 事件上用户自定义的标签 用户自定义的标签

保留指标

指标名 中文名 必需 类型 说明
__title 事件标题 string 关键事件标题
__content(原名 $des) 事件内容 string 支持 markdown 格式
__suggestion 事件处理建议 string 支持 markdown 格式
__duration 事件的持续时间 int 单位为微秒
__dimensions 触发维度 JSONString 例如:假设新建触发规则时设置的触发维度为 host,cpu,则该值为 ["host","cpu"]
__targets 检测规则的检测指标 产生该事件的检测规则的检测指标
__checkDps 展示检测的目标对象数据点 用于在事件中绘制图表,可向用户直观的展示告警产生时的数据表现
__outlierDps 异常的数据点 检测时异常的数据点
__extendDps 其他用于观察的数据点,用于绘图 比如区间检测的上下限

__eventId 自动补全算法

将事件的标签排除 __status 标签后将 tagkey 进行序列化后加上事件的 __title/ 作为前缀计算 MD5 值,将该值作为 __eventId

event_key = json.dumps(tags_without_status, ensure_ascii=False, sort_keys=True, separators=(',', ':'))
__eventId = MD5(__title/event_key)
__targets:[
    {
            "qtype": "http",
            "query": {
                "fields": [{
                    "alias": "M1",
                    "args": [{
                        "name": "感染人数"
                    }],
                    "fieldType": "integer",
                    "funcName": "mean",
                    "name": "感染人数"
                }],
                "filter": {
                    "tags": []
                },
                "groupBy": ["医院", "time(1m)"],
                "measurements": ["中国新冠舆情"],
                "period": "1m"
            }
        }
],
__checkDps:[
        {
        dps:[[1591701472000, 1.15],[1591701472000, 1.15]]]
    },
    {
        dps:[[1591701472000, 1.15],[1591701472000, 1.15]]]
    }
],
__outlierDps:[
    {
        dps:[[1591701472000, 1.15],[1591701472000, 1.15]]]
    },
    {
        dps:[[1591701472000, 1.15],[1591701472000, 1.15]]]
    }
]
__extendDps:[
    {
        dps:[[1591701472000, 1.15],[1591701472000, 1.15]]]
    },
    {
        dps:[[1591701472000, 1.15],[1591701472000, 1.15]]]
    }
]

请求示例

POST / HTTP/1.1
Host: {{dataway_route}}
X-Datakit-UUID: {{datakit_uuid}}
Content-Type: text/plain

__keyevent,__source=内部整理 __title="DataFlux 正式发布",__content=""DataFlux 实时大数据分析平台,面向企业提供全场景的数据分析能力,帮助企业从数据中洞察业务,释放数据价值,从而实现商业成功" 1577196000000000000
__keyevent,__source=网络采集 __title="伊朗发射导弹袭击美国驻伊拉克军事基地",__content="伊朗向驻伊拉克的美军部队发射了十数枚弹道导弹,这是德黑兰首次对美国杀死该国军事指挥官卡西姆•苏莱曼尼(Qassem Soleimani)进行军事报复" 1578448238000000000

上报对象数据 | /v1/write/object | POST

  • 接口描述:调用该接口上报事件数据到 DataFlux 中

  • Content-Type: application/json

  • 请求的 Body 格式为 JSONArray,数组中的一个元素对应一个对象

对象 Item

字段名 中文名 必需 说明
__name 对象名称 当前对象的名称,同一个分类下,对象名称如果重复,会覆盖原有数据
__class 对象分类 当前对象的分类,分类值用户可自定义
__content 对象主体 当前对象主体内容,json字符串, key-value 对

请求示例

POST / HTTP/1.1
Host: {{dataway_route}}
X-Datakit-UUID: {{datakit_uuid}}
Content-Type: application/json

 [
    {
            "__name":"objectName",
            "__class": "objectClass",
            "__content":"{
                    \"customTag\": \"customTagValue\"
            }"
    },
    {
            "__name":"objectName",
            "__class": "objectClass",
            "__content": "{
                    \"customTag\": \"customTagValue\"
            }"
    }
]

数据写入 SDK

DataWay 配置和管理接口

/v1/config | GET

获取 DataWay 配置文件,需要提供配置密码。

参数 描述 类型 required? 默认值
pwd 获取配置文件需要提供密码 str Yes 该密码在 DataWay 安装串中传入

请求示例(可将返回定位到一个 yaml 文件):

curl http://<DataWay-host>:9528/v1/config?pwd=<your-password>
curl http://<DataWay-host>:9528/v1/config?pwd=<your-password> > DataWay.yaml

/v1/config | POST

修改 DataWay 配置文件

参数 描述 类型 required? 默认值
pwd 修改配置文件需要提供密码 str Yes 该密码在 DataWay 安装串中传入

注意:

  • 该接口不支持上传 Lua 文件,但可以更改 DataWay 配置文件中现有 Lua 的配置(比如去掉某路由上的一个 lua 文件配置、禁用路由上的 Lua 功能等)。

  • 不能远程修改如下配置:

    • HTTP 配置:包括 DataWay 端口,Kodo 服务器地址等
    • 日志配置:包括 DataWay 应用日志,API 网管访问日志
    • 不允许修改 Cache 目录配置
    • 不支持更换 DataWay UUID、Token、是否在 Docker 运行(within_docker) 参数

一般情况下是管理人员通过远程 POST 一个请求给 DataWay,同时附上 yaml 格式的配置信息(注意 yaml 格式必须正确)

请求示例(请以你自己 get 到 config 作为测试,下面的示例可能过时):

curl -vv -XPOST "http://0.0.0.0:39528/v1/config?pwd=<your-password>" -d '
uuid: agnt_1af09c4c27c111eab6aaae10aab560b9
token: tkn_6cb6e15edd9a40629673ee7ecd5b9f6e
remote_host: http://10.100.64.106:29527
collect_second: 60
bind: :29528
within_docker: true
access_key: hilIxbDzFK7PB9qH
secret_key: 83i6q1WYSCZcwkRv52tNXFBKumLdJs9M
log: /usr/local/cloudcare/forethought/dataway/log
log_level: debug
gin_log: /usr/local/cloudcare/forethought/dataway/log
cache_dir: ""
routes_config:
- name: default
  disable_type_check: false
  ak_open: false
templateretags: {}
batch_config:
  workers: 16
  batch_size: 100
  batch_interval: 60
  queue_size: 128'

HTTP/1.1 200 OK
Content-Length: 40

{
    "code":200,
    "errorCode":"",
    "message":""
}

/v1/reload | POST

重新 reload DataWay 配置并重新载入关键模块(注意不是重启 DataWay)

参数 描述 类型 required? 默认值
pwd config API 调用密码 str Yes

示例:

curl -vv -XPOST "http://<DataWay-host>:9528/v1/reload?pwd=<your-password>"

{
    "code":200,
    "errorCode":"",
    "message":""
}

[Lua操作相关API](## Lua 操作相关 API)

以下 API 便于通过 curl 或 post(wo)man 等工具,直接读写 DataWay 上的 Lua 文件。所有 Lua 相关的 API 操作不会立即生效,需要调用上面的 POST /v1/config 接口以及(或) POST /v1/reload 接口才能生效。

/v1/lua | POST

上传一段 Lua 代码到 DataWay 指定的 Lua 目录下

参数 描述 类型 required? 默认值
pwd config API 调用密码 str Yes
fpath Lua 代码存入路径 str Yes
force 强制覆盖 any-string false

关于 fpath:

  • 只能使用相对路径,绝对路径将被报错。
  • 如果 fpath 在 DataWay 上已经是一个文件夹,即使用了 force 参数也一样会报错。即不能覆盖 DataWay 上的文件夹
  • 最终 Lua 代码将存入 <DataWay-workdir>/lua/<fpath>
  • 请使用 Linux 目录分隔符(若使用 Windows 分隔符, behavior undefined)

示例:如下代码将存入 <DataWay-workdir>/lua/test/x.lua:

curl -vv -XPOST "http://0.0.0.0:39528/v1/lua?pwd=<your-password>&fpath=test/x.lua" -d'
function handle(points)
    -- this is comments
    return points
end'

/v1/lua | GET

从 DataWay 指定的 Lua 目录下,下载一段 Lua 代码

参数 描述 类型 required? 默认值
pwd config API 调用密码 str Yes
fpath Lua 代码路径 str Yes

关于 fpath:

  • 只能使用相对路径,绝对路径将被报错。另外,不能下载 Lua 代码目录
  • 最终 Lua 代码以 text 形式返回,调用者负责存入文件
  • 请使用 Linux 目录分隔符(若使用 Windows 分隔符, behavior undefined)

示例:

curl -vv -XGET "http://0.0.0.0:39528/v1/lua?pwd=<your-password>&fpath=test/x.lua"

HTTP/1.1 200 OK
Content-Type: text/plain;charset=UTF-8
X-Trace-Id: trace_6d58faad-9be2-42ae-9fa8-f119f3442704
Content-Length: 64

function handle(points)
    -- this is another lua
    return points
end

失败示例:

curl -vv -XGET "http://0.0.0.0:39528/v1/lua?pwd=<your-password>&fpath=test/not-exists.lua"

HTTP/1.1 404 Not Found

{
    "code":404,
    "errorCode":"dataway.luaPathNotExists",
    "message":"lua path not exists"
}

/v1/lua/list | GET

列举 DataWay 所有 Lua 信息

参数 描述 类型 required? 默认值
pwd config API 调用密码 str Yes

示例:

curl -vv -XGET "http://0.0.0.0:39528/v1/lua/list?pwd=<your-password>"

{
  "code": 200,
  "content": [
    {
      "path": "test/x.lua",
      "abs_path": "/usr/local/cloudcare/forethought/dataway/lua/test/x.lua",
      "host_path": "/dataway-data/agnt_agnt_1af09c4c27c111eab6aaae10aab560b9/lua/test/x.lua",
      "size": 64,
      "modtime_utc": "2020-03-05 14:38:42",
      "within_docker": true,
      "enabled_routes": [
        "default"
      ]
    },
    {
      "path": "test/y.lua",
      "abs_path": "/usr/local/cloudcare/forethought/dataway/lua/test/y.lua",
      "host_path": "/dataway-data/agnt_agnt_1af09c4c27c111eab6aaae10aab560b9/lua/test/y.lua",
      "size": 64,
      "modtime_utc": "2020-03-05 14:23:10",
      "within_docker": true,
      "enabled_routes": [
        "default"
      ]
    }
  ],
  "errorCode": ""
}

字段说明:

  • path: <DataWay-workdir>/lua/ 下的目录地址
  • abs_path: Lua 文件在 DataWay 上的绝对地址
  • host_path: Lua 文件在宿主机上的绝对地址(如果 DataWay 在宿主机运行,该目录和 abs_path 一致)
  • size: Lua 文件大小(字节)
  • modtime_utc: Lua 文件的修改时间
  • within_docker: DataWay 是否运行在 Docker 中(用于判断 Lua 文件存放位置)
  • enabled_routes: 该 Lua 在哪些路由下服役(被禁用 Lua 的路由不包含在此)

/v1/lua | DELETE

删除 <DataWay-work-dir>/lua 目录下的文件

参数 描述 类型 required? 默认值
pwd config API 调用密码 str Yes
fpath Lua 代码路径(可以是整个目录) str Yes
force 强制删除 any-string false

注意:若要删除当前正在路由上被使用的 Lua,需指定 force 参数。就是如此,config 不会因为该 Lua 被删除而更改,强制删除 Lua 后,如果不更新 config,后续的启动不会受影响(但有 Error 日志:lua 不存在)。建议强制删除 Lua 后,也一并更新 config。比较温和的方式是,先更新 config,移除对应路由下的 Lua 配置。而后再调用本接口移除 Lua 文件(此时无需加 force 参数)

示例: 删除 test 目录下所有 lua 文件

curl -vv -XDELETE "http://0.0.0.0:39528/v1/lua?pwd=abc123CBA&fpath=test"

{
    "code":403,
    "errorCode":"dataway.luaBeenUsedBySomeRouter",
    "message":"lua been used by some router"
}

curl -vv -XDELETE "http://0.0.0.0:39528/v1/lua?pwd=abc123CBA&fpath=test/z.lua"

{
    "code":200,
    "errorCode":"",
    "message":""
} 

/v1/license | POST

更新 DataWay License

参数 描述 类型 required? 默认值
pwd config API 调用密码 str Yes

注意:如果当前 DataWay 上 license 和提交的 license 一样,则报错(DataWay 认为这是无意义的行为)。

示例:

curl -vv -XPOST "http://0.0.0.0:39528/v1/license?pwd=abc123CBA" -d'
Author = "6a5rS5aUxxxxxxxxxxxx"
Effect = "2020-01-09 02:30:13"
Expire = "2020-04-09 02:30:13"
Owner = "test"
License = "ApzL3kxRLqv6Ag/VWazi3I6L0pdAV8sLNnxq0X5ce47v:AlcJvsKjNaxdOUEG7musr4xxxxxxxxxxxxxxxxxxxxxx"
Version = "SAAS"
Sign = "aa1b6f2391xxxxxxxxxxxxxxxxxxxxxx"
Date = "2020-01-09 02:30:13"
'

{
    "code":200,
    "errorCode":"",
    "message":""
}