跳至主要內容

RESTful API V2

大约 9 分钟

RESTful API V2

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 cm9vdDpyb290

  • 若用户名密码认证失败，则返回如下信息：

    HTTP 状态码：401

    返回结构体如下

    {
  "code": 600,
  "message": "WRONG_LOGIN_PASSWORD_ERROR"
}

  • 若未设置 Authorization，则返回如下信息：

    HTTP 状态码：401

    返回结构体如下

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

接口

ping

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

请求方式：GET

请求路径：http://ip: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://ip: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.** 这种查找方式。

  1. 请求示例 表达式查询:
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
    ]
  ]
}

2.请求示例 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"
    ]
  ]
}
  1. 请求示例 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"
    ]
  ]
}
  1. 请求示例 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
    ]
  ]
}
  1. 请求示例 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
    ]
  ]
}
  1. 请求示例 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",
      ...
    ]
  ]
}
  1. 请求示例 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
    ]
  ]
}
  1. 请求示例 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
    ]
  ]
}
  1. 请求示例 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
    ]
  ]
}
  1. 请求示例 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
    ]
  ]
}
  1. 请求示例 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"
    ]
  ]
}
  1. 请求示例 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"
    ]
  ]
}
  1. 请求示例 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"
    ]
  ]
}
  1. 请求示例 原始聚合查询:
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
    ]
  ]
}
  1. 请求示例 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
    ]
  ]
}
  1. 请求示例 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
    ]
  ]
}
  1. 请求示例 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"
    ]
  ]
}
  1. 请求示例 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."
}
  1. 请求示例 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."
}
  1. 请求示例 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://ip: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://ip: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://ip: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 IoTDB, IoTDB, Apache, the Apache feather logo, and the Apache IoTDB project logo are either registered trademarks or trademarks of The Apache Software Foundation in all countries

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