未验证 提交 5b010953 编写于 作者: B Bo Ding 提交者: GitHub

adjust new docs structure (#10897)

* adjust doc structure

* adjust doc structure

* modify sample code path
上级 2bb6383c
```go
package main
import (
"database/sql"
"fmt"
_ "github.com/taosdata/driver-go/v2/taosRestful"
)
func main() {
var taosDSN = "root:taosdata@http(localhost:6041)/test"
taos, err := sql.Open("taosRestful", taosDSN)
if err != nil {
fmt.Println("failed to connect TDengine, err:", err)
return
}
fmt.Println("Connected")
defer taos.Close()
}
{{#include docs-examples/go/connect/restexample/main.go}}
```
[查看完整程序](https://github.com/taosdata/docs.taosdata.com/blob/master/examples/go/connect/restexample/main.go)
[查看完整程序](https://github.com/taosdata/TDengine/blob/develop/docs-examples/go/connect/restexample/main.go)
```java
package com.taos.example;
import com.taosdata.jdbc.TSDBDriver;
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.SQLException;
import java.util.Properties;
public class RESTConnectExample {
public static void main(String[] args) throws SQLException {
String jdbcUrl = "jdbc:TAOS-RS://localhost:6041?user=root&password=taosdata";
Properties connProps = new Properties();
connProps.setProperty(TSDBDriver.PROPERTY_KEY_CHARSET, "UTF-8");
connProps.setProperty(TSDBDriver.PROPERTY_KEY_LOCALE, "en_US.UTF-8");
connProps.setProperty(TSDBDriver.PROPERTY_KEY_TIME_ZONE, "UTC-8");
Connection conn = DriverManager.getConnection(jdbcUrl, connProps);
System.out.println("Connected");
conn.close();
}
}
{{#include docs-examples/java/src/main/java/com/taos/example/RESTConnectExample.java}}
```
[查看完整程序](https://github.com/taosdata/docs.taosdata.com/blob/master/examples/java/src/main/java/com/taos/example/RESTConnectExample.java)
[查看完整程序](https://github.com/taosdata/TDengine/blob/develop/docs-examples/java/src/main/java/com/taos/example/RESTConnectExample.java)
<!-- {{#include examples/java/src/main/java/com/taos/example/RESTConnectExample.java}} -->
```rust
use libtaos::*;
fn taos_connect() -> Result<Taos, Error> {
TaosCfgBuilder::default()
.ip("127.0.0.1")
.user("root")
.pass("taosdata")
.db("log")
.port(6030u16)
.build()
.expect("ToasCfg builder error")
.connect()
}
fn main() {
#[allow(unused_variables)]
let taos = taos_connect().unwrap();
println!("Connected")
}
{{#include docs-examples/rust/restexample/examples/connect.rs}}
```
[查看完整程序](https://github.com/taosdata/docs.taosdata.com/blob/master/examples/rust/restexample/examples/connect.rs)
[查看完整程序](https://github.com/taosdata/TDengine/blob/develop/docs-examples/rust/restexample/examples/connect.rs)
# 普通写入
# SQL 写入
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
......@@ -34,17 +34,25 @@ INSERT INTO d1001 VALUES (1538548685000, 10.3, 219, 0.31) (1538548695000, 12.6,
:::
## RESTful
## 示例程序
<Tabs>
<TabItem label="curl" value="curl"> </TabItem>
### 普通 SQL 写入
<Tabs defaultValue="java">
<TabItem label="Java" value="java"></TabItem>
<TabItem label="Python" value="Python"></TabItem>
<TabItem label="Go" value="go"></TabItem>
<TabItem label="C" value="c"></TabItem>
<TabItem label="Rust" value="rust"></TabItem>
<TabItem label="NodeJS" value="node"></TabItem>
<TabItem label="Node.js" value="nodejs"></TabItem>
<TabItem label="C#" value="csharp"></TabItem>
</Tabs>
## 本地驱动
### 动态绑定写入
(补充介绍)
### 示例代码
<Tabs defaultValue="java">
<TabItem label="Java" value="java"></TabItem>
......
---
sidebar_label: InfluxDB Line 协议
---
# InfluxDB Line 协议
## 示例代码
# 动态绑定写入
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
(补充介绍)
## 示例代码
<Tabs defaultValue="java">
<TabItem label="Java" value="java"></TabItem>
<TabItem label="Python" value="Python"></TabItem>
<TabItem label="Go" value="go"></TabItem>
<TabItem label="C" value="c"></TabItem>
<TabItem label="Rust" value="rust"></TabItem>
<TabItem label="Node.js" value="nodejs"></TabItem>
<TabItem label="C#" value="csharp"></TabItem>
</Tabs>
---
sidebar_label: OpentsDB Telnet 协议
---
# OpentsDB Telnet 协议
## 示例代码
\ No newline at end of file
# Schemaless 写入
## 前言
在物联网应用中,常会采集比较多的数据项,用于实现智能控制、业务分析、设备监控等。由于应用逻辑的版本升级,或者设备自身的硬件调整等原因,数据采集项就有可能比较频繁地出现变动。为了在这种情况下方便地完成数据记录工作,TDengine
从 2.2.0.0 版本开始,提供调用 Schemaless 写入方式,可以免于预先创建超级表/子表的步骤,随着数据写入接口能够自动创建与数据对应的存储结构。并且在必要时,Schemaless
将自动增加必要的数据列,保证用户写入的数据可以被正确存储。
无模式写入方式建立的超级表及其对应的子表与通过 SQL 直接建立的超级表和子表完全没有区别,你也可以通过,SQL 语句直接向其中写入数据。需要注意的是,通过无模式写入方式建立的表,其表名是基于标签值按照固定的映射规则生成,所以无法明确地进行表意,缺乏可读性。
## 无模式写入行协议
TDengine 的无模式写入的行协议兼容 InfluxDB 的 行协议(Line Protocol)、OpenTSDB 的 telnet 行协议、OpenTSDB 的 JSON 格式协议。但是使用这三种协议的时候,需要在 API 中指定输入内容使用解析协议的标准。
## 示例代码
---
sidebar_label: OpentsDB JSON 格式协议
---
# OpentsDB JSON 格式协议
## 示例代码
# 其它写入方式
## icinga2 直接写入(通过 taosAdapter)
- 参考链接 `https://icinga.com/docs/icinga-2/latest/doc/14-features/#opentsdb-writer` 使能 opentsdb-writer
- 使能 taosAdapter 配置项 opentsdb_telnet.enable
- 修改配置文件 /etc/icinga2/features-enabled/opentsdb.conf
```
object OpenTsdbWriter "opentsdb" {
host = "host to taosAdapter"
port = 6048
}
```
taosAdapter 相关配置参数请参考 taosadapter --help 命令输出以及相关文档。
## TCollector 直接写入(通过 taosAdapter)
TCollector 是一个在客户侧收集本地收集器并发送数据到 OpenTSDB 的进程,taosAdaapter 可以支持接收 TCollector 的数据并写入到 TDengine 中。
使能 taosAdapter 配置项 opentsdb_telnet.enable
修改 TCollector 配置文件,修改 OpenTSDB 宿主机地址为 taosAdapter 被部署的地址,并修改端口号为 taosAdapter 使用的端口(默认 6049)。
taosAdapter 相关配置参数请参考 taosadapter --help 命令输出以及相关文档。
## EMQ Broker 直接写入
MQTT 是流行的物联网数据传输协议,[EMQ](https://github.com/emqx/emqx)是一开源的 MQTT Broker 软件,无需任何代码,只需要在 EMQ Dashboard 里使用“规则”做简单配置,即可将 MQTT 的数据直接写入 TDengine。EMQ X 支持通过 发送到 Web 服务的方式保存数据到 TDEngine,也在企业版上提供原生的 TDEngine 驱动实现直接保存。详细使用方法请参考 [EMQ 官方文档](https://docs.emqx.io/broker/latest/cn/rule/rule-example.html#%E4%BF%9D%E5%AD%98%E6%95%B0%E6%8D%AE%E5%88%B0-tdengine)
## HiveMQ Broker 直接写入
[HiveMQ](https://www.hivemq.com/) 是一个提供免费个人版和企业版的 MQTT 代理,主要用于企业和新兴的机器到机器 M2M 通讯和内部传输,满足可伸缩性、易管理和安全特性。HiveMQ 提供了开源的插件开发包。可以通过 HiveMQ extension - TDengine 保存数据到 TDengine。详细使用方法请参考 [HiveMQ extension - TDengine 说明文档](https://github.com/huskar-t/hivemq-tdengine-extension/blob/b62a26ecc164a310104df57691691b237e091c89/README.md)
......@@ -103,18 +103,7 @@ Query OK, 5 row(s) in set (0.001521s)
## 示例代码
### RESTful
<Tabs defaultValue="java">
<TabItem label="Java" value="java"></TabItem>
<TabItem label="Go" value="go"></TabItem>
<TabItem label="Rust" value="rust"></TabItem>
<TabItem label="Node.js" value="nodejs"></TabItem>
</Tabs>
### 本地驱动
#### 同步查询
### 同步查询
<Tabs defaultValue="java">
<TabItem label="Java" value="java"></TabItem>
......@@ -126,10 +115,9 @@ Query OK, 5 row(s) in set (0.001521s)
<TabItem label="C#" value="csharp"></TabItem>
</Tabs>
#### 异步查询
### 异步查询
<Tabs defaultValue="java">
<TabItem label="Java" value="java"></TabItem>
<Tabs defaultValue="go">
<TabItem label="Python" value="Python"></TabItem>
<TabItem label="Go" value="go"></TabItem>
<TabItem label="C" value="c"></TabItem>
......
---
sidebar_label: Prometheus 直接写入
sidebar_label: Prometheus
---
# Prometheus 直接写入(通过 taosAdapter)
# Prometheus 写入
remote_read 和 remote_write 是 Prometheus 数据读写分离的集群方案。
只需要将 remote_read 和 remote_write url 指向 taosAdapter 对应的 url 同时设置 Basic 验证即可使用。
......
---
sidebar_label: Telegraf 直接写入
sidebar_label: Telegraf
---
# Telegraf 直接写入(通过 taosAdapter)
# Telegraf 写入
安装 Telegraf 请参考[官方文档](https://portal.influxdata.com/downloads/)
......
---
sidebar_label: collectd 直接写入
sidebar_label: collectd
---
# collectd 直接写入(通过 taosAdapter)
# collectd 写入
安装 collectd,请参考[官方文档](https://collectd.org/download.shtml)
......
---
sidebar_label: StatsD 直接写入
sidebar_label: StatsD
---
# StatsD 直接写入(通过 taosAdapter)
# StatsD 直接写入
安装 StatsD
请参考[官方文档](https://github.com/statsd/statsd)
......@@ -28,4 +28,4 @@ port: 8125
taosAdapter 相关配置参数请参考 taosadapter --help 命令输出以及相关文档。
icinga2 可以收集监控和性能数据并写入 OpenTSDB,taosAdapter 可以支持接收 icinga2 的数据并写入到 TDengine 中。
\ No newline at end of file
icinga2 可以收集监控和性能数据并写入 OpenTSDB,taosAdapter 可以支持接收 icinga2 的数据并写入到 TDengine 中。
---
sidebar_label: icinga2
---
# icinga2 写入
- 参考链接 `https://icinga.com/docs/icinga-2/latest/doc/14-features/#opentsdb-writer` 使能 opentsdb-writer
- 使能 taosAdapter 配置项 opentsdb_telnet.enable
- 修改配置文件 /etc/icinga2/features-enabled/opentsdb.conf
```
object OpenTsdbWriter "opentsdb" {
host = "host to taosAdapter"
port = 6048
}
```
taosAdapter 相关配置参数请参考 taosadapter --help 命令输出以及相关文档。
\ No newline at end of file
---
sidebar_label: TCollector
---
# TCollector 写入
TCollector 是一个在客户侧收集本地收集器并发送数据到 OpenTSDB 的进程,taosAdaapter 可以支持接收 TCollector 的数据并写入到 TDengine 中。
使能 taosAdapter 配置项 opentsdb_telnet.enable
修改 TCollector 配置文件,修改 OpenTSDB 宿主机地址为 taosAdapter 被部署的地址,并修改端口号为 taosAdapter 使用的端口(默认 6049)。
taosAdapter 相关配置参数请参考 taosadapter --help 命令输出以及相关文档。
---
sidebar_label: EMQ Broker
---
# EMQ Broker 写入
MQTT 是流行的物联网数据传输协议,[EMQ](https://github.com/emqx/emqx)是一开源的 MQTT Broker 软件,无需任何代码,只需要在 EMQ Dashboard 里使用“规则”做简单配置,即可将 MQTT 的数据直接写入 TDengine。EMQ X 支持通过 发送到 Web 服务的方式保存数据到 TDEngine,也在企业版上提供原生的 TDEngine 驱动实现直接保存。详细使用方法请参考 [EMQ 官方文档](https://docs.emqx.io/broker/latest/cn/rule/rule-example.html#%E4%BF%9D%E5%AD%98%E6%95%B0%E6%8D%AE%E5%88%B0-tdengine)
---
sidebar_label: HiveMQ Broker
---
# HiveMQ Broker 写入
[HiveMQ](https://www.hivemq.com/) 是一个提供免费个人版和企业版的 MQTT 代理,主要用于企业和新兴的机器到机器 M2M 通讯和内部传输,满足可伸缩性、易管理和安全特性。HiveMQ 提供了开源的插件开发包。可以通过 HiveMQ extension - TDengine 保存数据到 TDengine。详细使用方法请参考 [HiveMQ extension - TDengine 说明文档](https://github.com/huskar-t/hivemq-tdengine-extension/blob/b62a26ecc164a310104df57691691b237e091c89/README.md)
---
sidebar_position: 7
---
# RESTful Connector
# RESTful API
为支持各种不同类型平台的开发,TDengine 提供符合 REST 设计标准的 API,即 RESTful API。为最大程度降低学习成本,不同于其他数据库 RESTful API 的设计方法,TDengine 直接通过 HTTP POST 请求 BODY 中包含的 SQL 语句来操作数据库,仅需要一个 URL。RESTful 连接器的使用参见[视频教程](https://www.taosdata.com/blog/2020/11/11/1965.html)。
注意:与原生连接器的一个区别是,RESTful 接口是无状态的,因此 `USE db_name` 指令没有效果,所有对表名、超级表名的引用都需要指定数据库名前缀。(从 2.2.0.0 版本开始,支持在 RESTful url 中指定 db_name,这时如果 SQL 语句中没有指定数据库名前缀的话,会使用 url 中指定的这个 db_name。从 2.4.0.0 版本开始,RESTful 默认由 taosAdapter 提供,要求必须在 url 中指定 db_name。)
### 安装
## 安装
RESTful 接口不依赖于任何 TDengine 的库,因此客户端不需要安装任何 TDengine 的库,只要客户端的开发语言支持 HTTP 协议即可。
### 验证
## 验证
在已经安装 TDengine 服务器端的情况下,可以按照如下方式进行验证。
......@@ -74,9 +70,9 @@ h1.taosdata.com:6041/rest/sql
}
```
### RESTful 连接器的使用
## RESTful 连接器的使用
#### HTTP 请求格式
### HTTP 请求格式
```
http://<fqdn>:<port>/rest/sql/[db_name]
......@@ -120,7 +116,7 @@ curl -u username:password -d '<SQL>' <ip>:<PORT>/rest/sql/[db_name]
其中,`TOKEN` 为 `{username}:{password}` 经过 Base64 编码之后的字符串,例如 `root:taosdata` 编码后为 `cm9vdDp0YW9zZGF0YQ==`
### HTTP 返回格式
## HTTP 返回格式
返回值为 JSON 格式,如下:
......@@ -145,11 +141,20 @@ curl -u username:password -d '<SQL>' <ip>:<PORT>/rest/sql/[db_name]
- data: 具体返回的数据,一行一行的呈现,如果不返回结果集,那么就仅有 [[affected_rows]]。data 中每一行的数据列顺序,与 column_meta 中描述数据列的顺序完全一致。
- rows: 表明总共多少行数据。
<a class="anchor" id="column_meta"></a>column_meta 中的列类型说明: * 1:BOOL * 2:TINYINT
* 3:SMALLINT * 4:INT * 5:BIGINT * 6:FLOAT * 7:DOUBLE * 8:BINARY * 9:TIMESTAMP
* 10:NCHAR
column_meta 中的列类型说明:
- 1:BOOL
- 2:TINYINT
- 3:SMALLINT
- 4:INT
- 5:BIGINT
- 6:FLOAT
- 7:DOUBLE
- 8:BINARY
- 9:TIMESTAMP
- 10:NCHAR
### 自定义授权码
## 自定义授权码
HTTP 请求中需要带有授权码 `<TOKEN>`,用于身份识别。授权码通常由管理员提供,可简单的通过发送 `HTTP GET` 请求来获取授权码,操作如下:
......@@ -181,7 +186,7 @@ curl http://192.168.0.1:6041/rest/login/root/taosdata
}
```
### 使用示例
## 使用示例
- 在 demo 库里查询表 d1001 的所有记录:
......@@ -227,9 +232,9 @@ curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'create database demo' 19
}
```
### 其他用法
## 其他用法
#### 结果集采用 Unix 时间戳
### 结果集采用 Unix 时间戳
HTTP 请求 URL 采用 `sqlt` 时,返回结果集的时间戳将采用 Unix 时间戳格式表示,例如
......@@ -257,7 +262,7 @@ curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'select * from demo.d1001
}
```
#### 结果集采用 UTC 时间字符串
### 结果集采用 UTC 时间字符串
HTTP 请求 URL 采用 `sqlutc` 时,返回结果集的时间戳将采用 UTC 时间字符串表示,例如
......@@ -285,7 +290,7 @@ HTTP 请求 URL 采用 `sqlutc` 时,返回结果集的时间戳将采用 UTC
}
```
### 重要配置项
## 重要配置项
下面仅列出一些与 RESTful 接口有关的配置参数,其他系统参数请看配置文件里的说明。(注意:配置修改后,需要重启 taosd 服务才能生效)
......
......@@ -4,22 +4,26 @@ TDengine 提供了丰富的应用程序开发接口,其中包括 C/C++、Java
![image-connecotr](/img/connector.png)
## 支持的系统
目前 TDengine 的连接器可支持的平台广泛,包括:X64/X86/ARM64/ARM32/MIPS/Alpha 等硬件平台,以及 Linux/Win64/Win32 等开发环境。对照矩阵如下:
| **CPU** | **OS** | **JDBC** | **Python** | **Go** | **Node.js** | **C#** | **Rust** | **RESTful** |
| ------------- | --------- | -------- | ---------- | ------ | ----------- | ------ | -------- | ----------- |
| **X86 64bit** | **Linux** | ● | ● | ● | ● | ● | ● | ● |
| **X86 64bit** | **Win64** | ● | ● | ● | ● | ● | ● | ● |
| **X86 64bit** | **Win32** | ● | ● | ● | ● | ○ | ○ | ● |
| **X86 32bit** | **Win32** | ○ | ○ | ○ | ○ | ○ | ○ | ● |
| **ARM64** | **Linux** | ● | ● | ● | ● | ○ | ○ | ● |
| **ARM32** | **Linux** | ● | ● | ● | ● | ○ | ○ | ● |
| **MIPS龙芯** | **Linux** | ○ | ○ | ○ | ○ | ○ | ○ | ○ |
| **Alpha申威** | **Linux** | ○ | ○ | -- | -- | -- | -- | ○ |
| **X86 海光** | **Linux** | ○ | ○ | ○ | -- | -- | -- | ○ |
| **CPU** | **OS** | **JDBC** | **Python** | **Go** | **Node.js** | **C#** | **Rust** | **RESTful** |
| -------------- | --------- | -------- | ---------- | ------ | ----------- | ------ | -------- | ----------- |
| **X86 64bit** | **Linux** | ● | ● | ● | ● | ● | ● | ● |
| **X86 64bit** | **Win64** | ● | ● | ● | ● | ● | ● | ● |
| **X86 64bit** | **Win32** | ● | ● | ● | ● | ○ | ○ | ● |
| **X86 32bit** | **Win32** | ○ | ○ | ○ | ○ | ○ | ○ | ● |
| **ARM64** | **Linux** | ● | ● | ● | ● | ○ | ○ | ● |
| **ARM32** | **Linux** | ● | ● | ● | ● | ○ | ○ | ● |
| **MIPS 龙芯** | **Linux** | ○ | ○ | ○ | ○ | ○ | ○ | ○ |
| **Alpha 申威** | **Linux** | ○ | ○ | -- | -- | -- | -- | ○ |
| **X86 海光** | **Linux** | ○ | ○ | ○ | -- | -- | -- | ○ |
其中 ● 表示官方测试验证通过,○ 表示非官方测试验证通过,-- 表示未经验证。
## 特性矩阵
连接器对 TDengine 特性的支持对照矩阵如下[1]:
| **Feature** | **Java** | **Python** | **Go** | **C#** | **Node.js** | **Rust** |
......
label: 服务的配置
\ No newline at end of file
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册