search
API DataWay API

DataWay API 说明文档

概述

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 编码后得出
  • Content-Type 表示请求内容的类型,例如 text/plain
  • Date 表示此次操作的时间,且必须为 HTTP1.1 规定的GMT时间,格式参见 RFC1123。例如 Wed, 20 Nov 2019 09:56:06 GMT

注意,日期的格式为:date1 = 2DIGIT SP month SP 4DIGIT; day month year (e.g., 02 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 Body。 行协议基本格式如:

measurement,<tag-list> <field-list> time
  • measurement 和 tag-list 之间以英文逗号分割
  • tag-list 和 field-list 之间以空格分割
  • field-list 和 time 之间以空格分割

其中

  • measurement 可以简单将其理解为数据库表名称
  • tag-list 均为字符串字典 {"key": "value"}
  • field-list 为动态类型的字典,如 {"int": 123, "float": 123.4, "string": "abc", "ok": true}
  • time 为整数类型,单位可以是 ns/us/ms/s/min/hour。如果单位不是 ns,则必须在 HTTP 请求(通过 precision 参数或 X-Precision Header)中指定其单位
  • 一个行协议中,必须至少有一个 field,time 和 tag 可以没有。当 time 缺失时,dataway 默认以 HTTP 请求接收到得到时间作为行协议中的时间

通用 HTTP Header 请求头参数

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

参数 对应 URL 查询参数 类型 required? 默认值 描述
X-Precision precision str No n(即纳秒) 指定数据的时间精度(n/ns/u/ms/s/m/h),假定采集器获取的时间精度是非纳秒级别(nns),那么就需要通过该参数指定对应的精度,不然 DataWay 无法将无精度的时间转成纳秒
X-Token token str Yes 指定数据的目标工作空间的 token往 OpenWay 打数据必须指定 X-Token,另外,如果通过 OpenWay 往系统工作空间打数据,可以用保留的 __internal__ 作为 token 参数
X-RP rp str No 可以为空 可指定数据在 DataFlux 中保留的时长,可选范围 rp0/rp1/rp2/rp3/rp4/rp5/rp6
X-Datakit-UUID 无,只能通过 HTTP header 指定 str No 不指定则以采集器 IP 作为 ID(容易混淆) 指定数据采集器的 ID
X-Version 无,只能通过 HTTP header 指定 str No 可以为空 指定数据采集器版本信息

说明:

X-Token 而言,默认是必填参数。具体情况,视 dataway 配置而定,如果 dataway 禁用了空 token 功能(默认),则 token 是必填参数,否则可以不填,dataway 认为就是用自己的 token(跟 __internal__ 行为等同)来上传。

各个 RP 的保留时长如下:

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

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

  • 接口描述:调用该接口上报指标数据到 DataFlux 中
  • Content-Type: text/plain

行协议约束(暂无)

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

  • 接口描述:调用该接口上报日志数据到 DataFlux 中
  • Content-Type: text/plain

行协议约束

  • measurement:最终作为日志的 source 字段存储
  • tags:无
  • field:无
  • time:无

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

  • 接口描述:调用该接口上报链路数据到 DataFlux 中
  • Content-Type: text/plain

行协议约束(暂无)因字段极多,建议不要自己使用 dataway API 上报数据,直接用 Datakit 来采集。

上报 RUM 数据 | /v1/write/rum | POST

  • 接口描述:调用该接口上报 RUM 数据到 DataFlux 中
  • Content-Type: text/plain

行协议约束(暂无)因字段极多,建议不要自己使用 dataway API 上报数据。可开启 Datakit RUM 采集器来接收数据。

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

  • 接口描述:调用该接口上报事件数据到 DataFlux 中
  • Content-Type: text/plain

行协议约束

  • measurement:必须是 keyevent
  • tags:必须包含 status/source 这几个 tag。其中 status 可选项 为 info/warning/error/critical/ok
  • field:必须包含这几个:
    • title:事件标题(string
    • event_id:事件 ID(string
    • date_range:检测区间时长,单位为秒(int
  • time:无约束

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

  • 接口描述:调用该接口上报事件数据到 DataFlux 中
  • Content-Type: text/plain

行协议约束

  • measurement:最终作为对象的 class 字段存储
  • tags:必须包含 name 这个 tag
  • field:必须至少一个 fields
  • time:无约束

更新对象数据 | /v1/update/object | POST

  • 接口描述:调用该接口上报事件数据到 DataFlux 中
  • Content-Type: text/plain

行协议约束

  • measurement:最终作为对象的 class 字段存储
  • tags:必须包含 name 这个 tag
  • field:无约束
  • time:无约束

数据写入 SDK

DataWay 配置和管理接口

/v1/keyconfig | GET

获取指定工作空间的某个key的配置信息;可以传多个keycode

参数 描述 类型 required?
X-Token 工作空间token信息, Header传输,同写入数据接口 str Yes
keycode 特定的key值 str Yes

请求示例:(以云关联相关的配置为例)

curl http://<DataWay-host>:9528/v1/keyconfig?keycode=CloudAccountAccessConfiguration
多个keycode示例: http://<DataWay-host>:9528/v1/keyconfig?keycode=xxx1&keycode=xxx2
HTTP/1.1 200 OK
{
    "content": {
        "CloudAccountAccessConfiguration": [{
            "name": "xxx",
            "uuid": "xxx",
            "ak_id": "xxx",
            "ak_secret": "xxx",
            "cloud_provider": "xxx"
        }]
    }
}

/v1/disable/keys | POST

获取指定工作空间的某个key的配置信息;可以传多个keycode

参数 描述 类型 required?
X-Token 工作空间token信息, Header传输,同写入数据接口 str Yes
keycode 特定的key值 str Yes
keyname 需要disable的字段名,如CloudProvidersAccessKey,为ak str-list Yes
keyvalues 需要disable的字段value列表,如CloudProvidersAccessKey, 为ak的value str-list Yes

请求示例:(以云关联相关的配置为例)

curl -XPOST http://<DataWay-host>:9528/v1/disable/keys

{
    "CloudProvidersAccessKey": {
        "keyname":"ak",
        "keyvalues":["ak1","ak2"...]
    }
}

HTTP/1.1 200 OK

/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":""
}