跳至主要內容

RESTful 服务

大约 9 分钟

RESTful 服务

IoTDB 的 RESTful 服务可用于查询、写入和管理操作,它使用 OpenAPI 标准来定义接口并生成框架。

开启RESTful 服务

RESTful 服务默认情况是关闭的

  • 开发者

    找到sever模块中org.apache.iotdb.db.conf.rest 下面的IoTDBRestServiceConfig类,修改enableRestService=true即可。

  • 使用者

    找到IoTDB安装目录下面的conf/iotdb-datanode.properties文件,将 enable_rest_service 设置为 true 以启用该模块。

     enable_rest_service=true
    

鉴权

除了检活接口 /ping,RESTful 服务使用了基础(basic)鉴权,每次 URL 请求都需要在 header 中携带 'Authorization': 'Basic ' + base64.encode(username + ':' + password)

示例中使用的用户名为:root,密码为:root,对应的 Basic 鉴权 Header 格式为

Authorization: Basic cm9vdDpyb2901
  • 若用户名密码认证失败,则返回如下信息:

    HTTP 状态码:401

    返回结构体如下

    {
      "code": 600,
      "message": "WRONG_LOGIN_PASSWORD_ERROR"
    }
    
  • 若未设置 Authorization,则返回如下信息:

    HTTP 状态码:401

    返回结构体如下

    {
      "code": 603,
      "message": "UNINITIALIZED_AUTH_ERROR"
    }
    

接口

ping

ping 接口可以用于线上服务检活。

请求方式:GET

请求路径:http://ipopen in new window:port/ping

请求示例:

$ curl http://127.0.0.1:18080/ping

返回的 HTTP 状态码:

  • 200:当前服务工作正常,可以接收外部请求。
  • 503:当前服务出现异常,不能接收外部请求。

响应参数:

参数名称参数类型参数描述
codeinteger状态码
messagestring信息提示

响应示例:

  • HTTP 状态码为 200 时:

    {
      "code": 200,
      "message": "SUCCESS_STATUS"
    }
    
  • HTTP 状态码为 503 时:

    {
      "code": 500,
      "message": "thrift service is unavailable"
    }
    

/ping 接口访问不需要鉴权。

query

query 接口可以用于处理数据查询和元数据查询。

请求方式:POST

请求头:application/json

请求路径:http://ipopen in new window:port/rest/v2/query

参数说明:

参数名称参数类型是否必填参数描述
sqlstring
row_limitinteger一次查询能返回的结果集的最大行数。
如果不设置该参数,将使用配置文件的 rest_query_default_row_size_limit 作为默认值。
当返回结果集的行数超出限制时,将返回状态码 411

响应参数:

参数名称参数类型参数描述
expressionsarray用于数据查询时结果集列名的数组,用于元数据查询时为null
column_namesarray用于元数据查询结果集列名数组,用于数据查询时为null
timestampsarray时间戳列,用于元数据查询时为null
valuesarray二维数组,第一维与结果集列名数组的长度相同,第二维数组代表结果集的一列

请求示例如下所示:

提示:为了避免OOM问题,不推荐使用select * from root.xx.** 这种查找方式。

请求示例 表达式查询:

curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"select s3, s4, s3 + 1 from root.sg27 limit 2"}' http://127.0.0.1:18080/rest/v2/query

响应示例:

{
  "expressions": [
    "root.sg27.s3",
    "root.sg27.s4",
    "root.sg27.s3 + 1"
  ],
  "column_names": null,
  "timestamps": [
    1635232143960,
    1635232153960
  ],
  "values": [
    [
      11,
      null
    ],
    [
      false,
      true
    ],
    [
      12.0,
      null
    ]
  ]
}

请求示例 show child paths:

curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"show child paths root"}' http://127.0.0.1:18080/rest/v2/query

响应示例:

{
  "expressions": null,
  "column_names": [
    "child paths"
  ],
  "timestamps": null,
  "values": [
    [
      "root.sg27",
      "root.sg28"
    ]
  ]
}

请求示例 show child nodes:

curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"show child nodes root"}' http://127.0.0.1:18080/rest/v2/query

响应示例:

{
  "expressions": null,
  "column_names": [
    "child nodes"
  ],
  "timestamps": null,
  "values": [
    [
      "sg27",
      "sg28"
    ]
  ]
}

请求示例 show all ttl:

curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"show all ttl"}' http://127.0.0.1:18080/rest/v2/query

响应示例:

{
  "expressions": null,
  "column_names": [
    "database",
    "ttl"
  ],
  "timestamps": null,
  "values": [
    [
      "root.sg27",
      "root.sg28"
    ],
    [
      null,
      null
    ]
  ]
}

请求示例 show ttl:

curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"show ttl on root.sg27"}' http://127.0.0.1:18080/rest/v2/query

响应示例:

{
  "expressions": null,
  "column_names": [
    "database",
    "ttl"
  ],
  "timestamps": null,
  "values": [
    [
      "root.sg27"
    ],
    [
      null
    ]
  ]
}

请求示例 show functions:

curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"show functions"}' http://127.0.0.1:18080/rest/v2/query

响应示例:

{
  "expressions": null,
  "column_names": [
    "function name",
    "function type",
    "class name (UDF)"
  ],
  "timestamps": null,
  "values": [
    [
      "ABS",
      "ACOS",
      "ASIN",
      ...
    ],
    [
      "built-in UDTF",
      "built-in UDTF",
      "built-in UDTF",
      ...
    ],
    [
      "org.apache.iotdb.db.query.udf.builtin.UDTFAbs",
      "org.apache.iotdb.db.query.udf.builtin.UDTFAcos",
      "org.apache.iotdb.db.query.udf.builtin.UDTFAsin",
      ...
    ]
  ]
}

请求示例 show timeseries:

curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"show timeseries"}' http://127.0.0.1:18080/rest/v2/query

响应示例:

{
  "expressions": null,
  "column_names": [
    "timeseries",
    "alias",
    "database",
    "dataType",
    "encoding",
    "compression",
    "tags",
    "attributes"
  ],
  "timestamps": null,
  "values": [
    [
      "root.sg27.s3",
      "root.sg27.s4",
      "root.sg28.s3",
      "root.sg28.s4"
    ],
    [
      null,
      null,
      null,
      null
    ],
    [
      "root.sg27",
      "root.sg27",
      "root.sg28",
      "root.sg28"
    ],
    [
      "INT32",
      "BOOLEAN",
      "INT32",
      "BOOLEAN"
    ],
    [
      "RLE",
      "RLE",
      "RLE",
      "RLE"
    ],
    [
      "SNAPPY",
      "SNAPPY",
      "SNAPPY",
      "SNAPPY"
    ],
    [
      null,
      null,
      null,
      null
    ],
    [
      null,
      null,
      null,
      null
    ]
  ]
}

请求示例 show latest timeseries:

curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"show latest timeseries"}' http://127.0.0.1:18080/rest/v2/query

响应示例:

{
  "expressions": null,
  "column_names": [
    "timeseries",
    "alias",
    "database",
    "dataType",
    "encoding",
    "compression",
    "tags",
    "attributes"
  ],
  "timestamps": null,
  "values": [
    [
      "root.sg28.s4",
      "root.sg27.s4",
      "root.sg28.s3",
      "root.sg27.s3"
    ],
    [
      null,
      null,
      null,
      null
    ],
    [
      "root.sg28",
      "root.sg27",
      "root.sg28",
      "root.sg27"
    ],
    [
      "BOOLEAN",
      "BOOLEAN",
      "INT32",
      "INT32"
    ],
    [
      "RLE",
      "RLE",
      "RLE",
      "RLE"
    ],
    [
      "SNAPPY",
      "SNAPPY",
      "SNAPPY",
      "SNAPPY"
    ],
    [
      null,
      null,
      null,
      null
    ],
    [
      null,
      null,
      null,
      null
    ]
  ]
}

请求示例 count timeseries:

curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"count timeseries root.**"}' http://127.0.0.1:18080/rest/v2/query

响应示例:

{
  "expressions": null,
  "column_names": [
    "count"
  ],
  "timestamps": null,
  "values": [
    [
      4
    ]
  ]
}

请求示例 count nodes:

curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"count nodes root.** level=2"}' http://127.0.0.1:18080/rest/v2/query

响应示例:

{
  "expressions": null,
  "column_names": [
    "count"
  ],
  "timestamps": null,
  "values": [
    [
      4
    ]
  ]
}

请求示例 show devices:

curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"show devices"}' http://127.0.0.1:18080/rest/v2/query

响应示例:

{
  "expressions": null,
  "column_names": [
    "devices",
    "isAligned"
  ],
  "timestamps": null,
  "values": [
    [
      "root.sg27",
      "root.sg28"
    ],
    [
      "false",
      "false"
    ]
  ]
}

请求示例 show devices with database:

curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"show devices with database"}' http://127.0.0.1:18080/rest/v2/query

响应示例:

{
  "expressions": null,
  "column_names": [
    "devices",
    "database",
    "isAligned"
  ],
  "timestamps": null,
  "values": [
    [
      "root.sg27",
      "root.sg28"
    ],
    [
      "root.sg27",
      "root.sg28"
    ],
    [
      "false",
      "false"
    ]
  ]
}

请求示例 list user:

curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"list user"}' http://127.0.0.1:18080/rest/v2/query

响应示例:

{
  "expressions": null,
  "column_names": [
    "user"
  ],
  "timestamps": null,
  "values": [
    [
      "root"
    ]
  ]
}

请求示例 原始聚合查询:

curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"select count(*) from root.sg27"}' http://127.0.0.1:18080/rest/v2/query

响应示例:

{
  "expressions": [
    "count(root.sg27.s3)",
    "count(root.sg27.s4)"
  ],
  "column_names": null,
  "timestamps": [
    0
  ],
  "values": [
    [
      1
    ],
    [
      2
    ]
  ]
}

请求示例 group by level:

curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"select count(*) from root.** group by level = 1"}' http://127.0.0.1:18080/rest/v2/query

响应示例:

{
  "expressions": null,
  "column_names": [
    "count(root.sg27.*)",
    "count(root.sg28.*)"
  ],
  "timestamps": null,
  "values": [
    [
      3
    ],
    [
      3
    ]
  ]
}

请求示例 group by:

curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"select count(*) from root.sg27 group by([1635232143960,1635232153960),1s)"}' http://127.0.0.1:18080/rest/v2/query

响应示例:

{
  "expressions": [
    "count(root.sg27.s3)",
    "count(root.sg27.s4)"
  ],
  "column_names": null,
  "timestamps": [
    1635232143960,
    1635232144960,
    1635232145960,
    1635232146960,
    1635232147960,
    1635232148960,
    1635232149960,
    1635232150960,
    1635232151960,
    1635232152960
  ],
  "values": [
    [
      1,
      0,
      0,
      0,
      0,
      0,
      0,
      0,
      0,
      0
    ],
    [
      1,
      0,
      0,
      0,
      0,
      0,
      0,
      0,
      0,
      0
    ]
  ]
}

请求示例 last:

curl -H "Content-Type:application/json"  -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"select last s3 from root.sg27"}' http://127.0.0.1:18080/rest/v2/query

响应示例:

{
  "expressions": null,
  "column_names": [
    "timeseries",
    "value",
    "dataType"
  ],
  "timestamps": [
    1635232143960
  ],
  "values": [
    [
      "root.sg27.s3"
    ],
    [
      "11"
    ],
    [
      "INT32"
    ]
  ]
}

请求示例 disable align:

curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"select * from root.sg27 disable align"}' http://127.0.0.1:18080/rest/v2/query

响应示例:

{
  "code": 407,
  "message": "disable align clauses are not supported."
}

请求示例 align by device:

curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"select count(s3) from root.sg27 align by device"}' http://127.0.0.1:18080/rest/v2/query

响应示例:

{
  "code": 407,
  "message": "align by device clauses are not supported."
}

请求示例 select into:

curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"select s3, s4 into root.sg29.s1, root.sg29.s2 from root.sg27"}' http://127.0.0.1:18080/rest/v2/query

响应示例:

{
  "code": 407,
  "message": "select into clauses are not supported."
}

nonQuery

请求方式:POST

请求头:application/json

请求路径:http://ipopen in new window:port/rest/v2/nonQuery

参数说明:

参数名称参数类型是否必填参数描述
sqlstring

请求示例:

curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"sql":"CREATE DATABASE root.ln"}' http://127.0.0.1:18080/rest/v2/nonQuery

响应参数:

参数名称参数类型参数描述
codeinteger状态码
messagestring信息提示

响应示例:

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

insertTablet

请求方式:POST

请求头:application/json

请求路径:http://ipopen in new window:port/rest/v2/insertTablet

参数说明:

参数名称参数类型是否必填参数描述
timestampsarray时间列
measurementsarray测点名称
data_typesarray数据类型
valuesarray值列,每一列中的值可以为 null
is_alignedboolean是否是对齐时间序列
devicestring设备名称

请求示例:

curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"timestamps":[1635232143960,1635232153960],"measurements":["s3","s4"],"data_types":["INT32","BOOLEAN"],"values":[[11,null],[false,true]],"is_aligned":false,"device":"root.sg27"}' http://127.0.0.1:18080/rest/v2/insertTablet

响应参数:

参数名称参数类型参数描述
codeinteger状态码
messagestring信息提示

响应示例:

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

insertRecords

请求方式:POST

请求头:application/json

请求路径:http://ipopen in new window:port/rest/v2/insertRecords

参数说明:

参数名称参数类型是否必填参数描述
timestampsarray时间列
measurements_listarray测点名称
data_types_listarray数据类型
values_listarray值列,每一列中的值可以为 null
devicesstring设备名称
is_alignedstring是否是对齐时间序列

请求示例:

curl -H "Content-Type:application/json" -H "Authorization:Basic cm9vdDpyb290" -X POST --data '{"timestamps":[1635232113960,1635232151960,1635232143960,1635232143960],"measurements_list":[["s33","s44"],["s55","s66"],["s77","s88"],["s771","s881"]],"data_types_list":[["INT32","INT64"],["FLOAT","DOUBLE"],["FLOAT","DOUBLE"],["BOOLEAN","TEXT"]],"values_list":[[1,11],[2.1,2],[4,6],[false,"cccccc"]],"is_aligned":false,"devices":["root.s1","root.s1","root.s1","root.s3"]}' http://127.0.0.1:18080/rest/v2/insertRecords

响应参数:

参数名称参数类型参数描述
codeinteger状态码
messagestring信息提示

响应示例:

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

配置

配置位于 iotdb-datanode.properties 中。

  • enable_rest_service 设置为 true 以启用该模块,而将 false 设置为禁用该模块。默认情况下,该值为 false
enable_rest_service=true
  • 仅在 enable_rest_service=true 时生效。将 rest_service_port 设置为数字(1025~65535),以自定义REST服务套接字端口。默认情况下,值为 18080
rest_service_port=18080
  • 将 'enable_swagger' 设置 'true' 启用swagger来展示rest接口信息, 而设置为 'false' 关闭该功能. 默认情况下,该值为 false
enable_swagger=false
  • 一次查询能返回的结果集最大行数。当返回结果集的行数超出参数限制时,您只会得到在行数范围内的结果集,且将得到状态码411
rest_query_default_row_size_limit=10000
  • 缓存客户登录信息的过期时间(用于加速用户鉴权的速度,单位为秒,默认是8个小时)
cache_expire=28800
  • 缓存中存储的最大用户数量(默认是100)
cache_max_num=100
  • 缓存初始容量(默认是10)
cache_init_num=10
  • REST Service 是否开启 SSL 配置,将 enable_https 设置为 true 以启用该模块,而将 false 设置为禁用该模块。默认情况下,该值为 false
enable_https=false
  • keyStore 所在路径(非必填)
key_store_path=
  • keyStore 密码(非必填)
key_store_pwd=
  • trustStore 所在路径(非必填)
trust_store_path=
  • trustStore 密码(非必填)
trust_store_pwd=
  • SSL 超时时间,单位为秒
idle_timeout=5000

Copyright © 2024 The Apache Software Foundation.
Apache and the Apache feather logo are trademarks of The Apache Software Foundation

Have a question? Connect with us on QQ, WeChat, or Slack. Join the community now.