xxq250
/
homework-jianmu
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
homework-jianmu/docs/en/14-reference/05-connector/60-rest-api.mdx

663 lines
17 KiB
Plaintext
Raw Blame History

---
title: REST API
description: Detailed introduction to the RESTful API provided by TDengine.
slug: /tdengine-reference/client-libraries/rest-api
---
To support the development of various types of platforms, TDengine provides an API that conforms to RESTful design standards, known as the REST API. To minimize the learning curve, unlike other database REST APIs, TDengine directly operates the database through SQL statements included in the HTTP POST request body, requiring only a URL.
:::note
One difference from the native connector is that the RESTful interface is stateless, so the `USE db_name` command has no effect. All references to table names and supertable names must specify the database name prefix. It supports specifying the db_name in the RESTful URL; in this case, if the SQL statement does not specify a database name prefix, the db_name specified in the URL will be used.
:::
## Installation
The RESTful interface does not depend on any TDengine libraries, so no TDengine libraries need to be installed on the client, as long as the client's development language supports HTTP protocol. TDengine's RESTful API is provided by [taosAdapter](../../components/taosadapter/). Before using the RESTful API, ensure that the `taosAdapter` is running properly.
## Verification
If the TDengine server is already installed, you can verify it as follows.
Use the `curl` tool (ensure it is installed) in an Ubuntu environment to verify whether the RESTful interface is functioning correctly. Before verification, ensure that the taosAdapter service is running. In Linux systems, this service is managed by systemd by default, and you can start it with the command `systemctl start taosadapter`.
The following example lists all databases. Please replace `h1.tdengine.com` and `6041` (the default value) with the actual FQDN and port number of the running TDengine service:
```bash
curl -L -H "Authorization: Basic cm9vdDp0YW9zZGF0YQ==" \
-d "select name, ntables, status from information_schema.ins_databases;" \
h1.tdengine.com:6041/rest/sql
```
The following return value indicates successful verification:
```json
{
"code": 0,
"column_meta": [
[
"name",
"VARCHAR",
64
],
[
"ntables",
"BIGINT",
8
],
[
"status",
"VARCHAR",
10
]
],
"data": [
[
"information_schema",
16,
"ready"
],
[
"performance_schema",
9,
"ready"
]
],
"rows": 2
}
```
## HTTP Request Format
```text
http://<fqdn>:<port>/rest/sql/[db_name][?tz=timezone[&req_id=req_id][&row_with_meta=true]]
```
Parameter descriptions:
- fqdn: FQDN or IP address of any host in the cluster.
- port: The value of the `httpPort` configuration item in the configuration file, defaulting to 6041.
- db_name: An optional parameter that specifies the default database name for the SQL statement to be executed.
- tz: An optional parameter that specifies the timezone for the returned time, following the IANA Time Zone rules, such as `America/New_York`.
- req_id: An optional parameter that specifies the request ID, which can be used for tracing.
- row_with_meta: An optional parameter that specifies whether each row of data carries the column names, defaulting to false. (Supported starting from version 3.3.2.0)
For example: `http://h1.taos.com:6041/rest/sql/test` points to the address `h1.taos.com:6041`, and sets the default database name to `test`.
The HTTP request header must include authentication information. TDengine supports both Basic and custom authentication mechanisms, and standard secure digital signature mechanisms for authentication will be provided in future versions.
- [Custom authentication information](#custom-authorization-code) is as follows:
```text
Authorization: Taosd <TOKEN>
```
- Basic authentication information is as follows:
```text
Authorization: Basic <TOKEN>
```
The body of the HTTP request contains a complete SQL statement. The data table in the SQL statement should provide the database prefix, such as `db_name.tb_name`. If the table name does not have a database prefix and the database name is not specified in the URL, the system will return an error. This is because the HTTP module is merely a simple forwarder and has no concept of the current DB.
To initiate an HTTP request using the custom authentication method with `curl`, the syntax is as follows:
```bash
curl -L -H "Authorization: Basic <TOKEN>" -d "<SQL>" <ip>:<PORT>/rest/sql/[db_name][?tz=timezone[&req_id=req_id][&row_with_meta=true]]
```
Alternatively,
```bash
curl -L -u username:password -d "<SQL>" <ip>:<PORT>/rest/sql/[db_name][?tz=timezone[&req_id=req_id][&row_with_meta=true]]
```
Where `TOKEN` is the Base64 encoded string of `{username}:{password}`, for example, `root:taosdata` encoded becomes `cm9vdDp0YW9zZGF0YQ==`.
## HTTP Return Format
### HTTP Response Codes
By default, `taosAdapter` will return a 200 response code for most C interface call errors, but the HTTP body will contain error information. Starting from `TDengine 3.0.3.0`, `taosAdapter` provides the configuration parameter `httpCodeServerError` to set whether to return non-200 HTTP response codes when C interfaces return errors. Regardless of whether this parameter is set, the response body will always contain detailed error codes and messages.
**When `httpCodeServerError` is false:**
| **Classification Description** | **HTTP Response Code** |
|------------------------------------|------------------------|
| C interface call success | 200 |
| C interface call error, not an authentication error | 200 |
| HTTP request URL parameter error | 400 |
| C interface call authentication error | 401 |
| Interface does not exist | 404 |
| Insufficient system resources | 503 |
**When `httpCodeServerError` is true:**
| **Classification Description** | **HTTP Response Code** |
|------------------------------------|------------------------|
| C interface call success | 200 |
| HTTP request URL parameter error and C interface call parameter parsing error | 400 |
| C interface call authentication error | 401 |
| Interface does not exist | 404 |
| C interface call network unavailable error | 502 |
| Insufficient system resources | 503 |
| Other C interface call errors | 500 |
C interface parameter parsing related error codes:
- TSDB_CODE_TSC_SQL_SYNTAX_ERROR (0x0216)
- TSDB_CODE_TSC_LINE_SYNTAX_ERROR (0x021B)
- TSDB_CODE_PAR_SYNTAX_ERROR (0x2600)
- TSDB_CODE_TDB_TIMESTAMP_OUT_OF_RANGE (0x060B)
- TSDB_CODE_TSC_VALUE_OUT_OF_RANGE (0x0224)
- TSDB_CODE_PAR_INVALID_FILL_TIME_RANGE (0x263B)
C interface authentication related error codes:
- TSDB_CODE_MND_USER_ALREADY_EXIST (0x0350)
- TSDB_CODE_MND_USER_NOT_EXIST (0x0351)
- TSDB_CODE_MND_INVALID_USER_FORMAT (0x0352)
- TSDB_CODE_MND_INVALID_PASS_FORMAT (0x0353)
- TSDB_CODE_MND_NO_USER_FROM_CONN (0x0354)
- TSDB_CODE_MND_TOO_MANY_USERS (0x0355)
- TSDB_CODE_MND_INVALID_ALTER_OPER (0x0356)
- TSDB_CODE_MND_AUTH_FAILURE (0x0357)
C interface network unavailable related error codes:
- TSDB_CODE_RPC_NETWORK_UNAVAIL (0x000B)
Error codes and descriptions can be found in [Error Codes](../../error-codes/).
### HTTP Body Structure
#### Successfully Executed Insert
Example:
```json
{
"code": 0,
"column_meta": [["affected_rows", "INT", 4]],
"data": [[0]],
"rows": 1
}
```
Description:
- code: (`int`) 0 indicates success.
- column_meta: (`[1][3]any`) returns only `[["affected_rows", "INT", 4]]`.
- rows: (`int`) returns only `1`.
- data: (`[][]any`) returns the number of affected rows.
#### Successfully Executed Query
Example:
```json
{
"code": 0,
"column_meta": [
["ts", "TIMESTAMP", 8],
["count", "BIGINT", 8],
["endpoint", "VARCHAR", 45],
["status_code", "INT", 4],
["client_ip", "VARCHAR", 40],
["request_method", "VARCHAR", 15],
["request_uri", "VARCHAR", 128]
],
"data": [
[
"2022-06-29T05:50:55.401Z",
2,
"LAPTOP-NNKFTLTG:6041",
200,
"172.23.208.1",
"POST",
"/rest/sql"
],
[
"2022-06-29T05:52:16.603Z",
1,
"LAPTOP-NNKFTLTG:6041",
200,
"172.23.208.1",
"POST",
"/rest/sql"
],
[
"2022-06-29T06:28:14.118Z",
1,
"LAPTOP-NNKFTLTG:6041",
200,
"172.23.208.1",
"POST",
"/rest/sql"
],
[
"2022-06-29T05:52:16.603Z",
2,
"LAPTOP-NNKFTLTG:6041",
401,
"172.23.208.1",
"POST",
"/rest/sql"
]
],
"rows": 4
}
```
Description:
- code: (`int`) 0 indicates success.
- column_meta: (`[][3]any`) Column information, each column is described by three values: column name (string), column type (string), and type length (int).
- rows: (`int`) Number of returned rows.
- data: (`[][]any`) Specific data content (the time format supports only RFC3339, with the result set being in UTC).
Column types use the following strings:
- "NULL"
- "BOOL"
- "TINYINT"
- "SMALLINT"
- "INT"
- "BIGINT"
- "FLOAT"
- "DOUBLE"
- "VARCHAR"
- "TIMESTAMP"
- "NCHAR"
- "TINYINT UNSIGNED"
- "SMALLINT UNSIGNED"
- "INT UNSIGNED"
- "BIGINT UNSIGNED"
- "JSON"
- "VARBINARY"
- "GEOMETRY"
The `VARBINARY` and `GEOMETRY` types return data as Hex strings. Example:
Prepare Data
```bash
create database demo
use demo
create table t(ts timestamp,c1 varbinary(20),c2 geometry(100))
insert into t values(now,'\x7f8290','point(100 100)')
```
Execute Query
```bash
curl --location 'http://<fqdn>:<port>/rest/sql' \
--header 'Content-Type: text/plain' \
--header 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' \
--data 'select * from demo.t'
```
Return Result
```json
{
"code": 0,
"column_meta": [
[
"ts",
"TIMESTAMP",
8
],
[
"c1",
"VARBINARY",
20
],
[
"c2",
"GEOMETRY",
100
]
],
"data": [
[
"2023-11-01T06:28:15.210Z",
"7f8290",
"010100000000000000000059400000000000005940"
]
],
"rows": 1
}
```
- `010100000000000000000059400000000000005940` is the [Well-Known Binary (WKB)](https://libgeos.org/specifications/wkb/) format for `point(100 100)`.
#### Error
Example:
```json
{
"code": 9728,
"desc": "syntax error near \"1\""
}
```
Description:
- code: (`int`) Error code.
- desc: (`string`) Error description.
Refer to the [Error Codes](../../error-codes/) for error codes and descriptions.
#### Return Key-Value Format Data
When the URL parameter `row_with_meta=true` is specified, the data in the returned `data` will change from an array format to an object format, where the object's key is the column name and the value is the data, as shown below:
Example of Insert Data Return
```json
{
"code": 0,
"column_meta": [
[
"affected_rows",
"INT",
4
]
],
"data": [
{
"affected_rows": 1
}
],
"rows": 1
}
```
Example of Query Data Return
```json
{
"code": 0,
"column_meta": [
[
"ts",
"TIMESTAMP",
8
],
[
"current",
"FLOAT",
4
],
[
"voltage",
"INT",
4
],
[
"phase",
"FLOAT",
4
],
[
"groupid",
"INT",
4
],
[
"location",
"VARCHAR",
24
]
],
"data": [
{
"ts": "2017-07-14T02:40:00.000Z",
"current": -2.498076,
"voltage": 0,
"phase": -0.846025,
"groupid": 8,
"location": "California.Sunnyvale"
}
],
"rows": 1
}
```
## Custom Authorization Code
The HTTP request needs to include the authorization code `<TOKEN>` for identity recognition. The authorization code is usually provided by the administrator and can be obtained simply by sending an `HTTP GET` request as follows:
```bash
curl http://<fqdn>:<port>/rest/login/<username>/<password>
```
Where `fqdn` is the FQDN or IP address of the TDengine database, `port` is the port number of the TDengine service, `username` is the database username, and `password` is the database password. The return value will be in JSON format, and the meanings of each field are as follows:
- status: The flag indicating the result of the request.
- code: The return value code.
- desc: The authorization code.
Example to Get Authorization Code:
```bash
curl http://192.168.0.1:6041/rest/login/root/taosdata
```
Return Value:
```json
{
"code": 0,
"desc": "/KfeAzX/f9na8qdtNZmtONryp201ma04bEl8LcvLUd7a8qdtNZmtONryp201ma04"
}
```
## Usage Examples
- Query all records of table `d1001` in the demo library:
```bash
curl -L -H "Authorization: Basic cm9vdDp0YW9zZGF0YQ==" -d "select * from demo.d1001" 192.168.0.1:6041/rest/sql
curl -L -H "Authorization: Taosd /KfeAzX/f9na8qdtNZmtONryp201ma04bEl8LcvLUd7a8qdtNZmtONryp201ma04" -d "select * from demo.d1001" 192.168.0.1:6041/rest/sql
```
Return Value:
```json
{
"code": 0,
"column_meta": [
[
"ts",
"TIMESTAMP",
8
],
[
"current",
"FLOAT",
4
],
[
"voltage",
"INT",
4
],
[
"phase",
"FLOAT",
4
]
],
"data": [
[
"2022-07-30T06:44:40.32Z",
10.3,
219,
0.31
],
[
"2022-07-30T06:44:41.32Z",
12.6,
218,
0.33
]
],
"rows": 2
}
```
- Create library `demo`:
```bash
curl -L -H "Authorization: Basic cm9vdDp0YW9zZGF0YQ==" -d "create database demo" 192.168.0.1:6041/rest/sql
curl -L -H "Authorization: Taosd /KfeAzX/f9na8qdtNZmtONryp201ma04bEl8LcvLUd7a8qdtNZmtONryp201ma04" -d "create database demo" 192.168.0.1:6041/rest/sql
```
Return Value:
```json
{
"code": 0,
"column_meta": [
[
"affected_rows",
"INT",
4
]
],
"data": [
[
0
]
],
"rows": 1
}
```
## Differences Between REST API in TDengine 2.x and 3.0
### URI
| URI | TDengine 2.x | TDengine 3.0 |
| :--------------------| :------------------: | :--------------------------------------------------: |
| /rest/sql | Supported | Supported (Response codes and body differ) |
| /rest/sqlt | Supported | No longer supported |
| /rest/sqlutc | Supported | No longer supported |
### HTTP Code
| HTTP Code | TDengine 2.x | TDengine 3.0 | Notes |
| :--------------------| :------------------: | :----------: | :-----------------------------------: |
| 200 | Supported | Supported | Correct return and taosc interface error return |
| 400 | Not supported | Supported | Parameter error return |
| 401 | Not supported | Supported | Authentication failure |
| 404 | Supported | Supported | Interface does not exist |
| 500 | Not supported | Supported | Internal error |
| 503 | Supported | Supported | Insufficient system resources |
### Response Codes and Body
#### TDengine 2.x Response Codes and Body
```JSON
{
"status": "succ",
"head": [
"name",
"created_time",
"ntables",
"vgroups",
"replica",
"quorum",
"days",
"keep1,keep2,keep(D)",
"cache(MB)",
"blocks",
"minrows",
"maxrows",
"wallevel",
"fsync",
"comp",
"precision",
"status"
],
"data": [
[
"log",
"2020-09-02 17:23:00.039",
4,
1,
1,
1,
10,
"30,30,30",
1,
3,
100,
4096,
1,
3000,
2,
"us",
"ready"
]
],
"rows": 1
}
```
```json
"data": [
[
"information_schema",
16,
"ready"
],
[
"performance_schema",
9,
"ready"
]
],
```
#### TDengine 3.0 Response Codes and Body
```JSON
{
"code": 0,
"column_meta": [
[
"name",
"VARCHAR",
64
],
[
"ntables",
"BIGINT",
8
],
[
"status",
"VARCHAR",
10
]
],
"data": [
[
"information_schema",
16,
"ready"
],
[
"performance_schema",
9,
"ready"
]
],
"rows": 2
}
```
Reference in New Issue View Git Blame Copy Permalink