From 71aedf0852a4556bc7c9fd1881e9ecd5b7c25018 Mon Sep 17 00:00:00 2001 From: Shuduo Sang Date: Sun, 24 Apr 2022 12:31:17 +0800 Subject: [PATCH] docs: connector refine (#11785) * docs: refine connector doc [TD-14839] * docs: use TDengine CLI [TD-14839] * docs: replace JNI with navtive connection [TD-14839] * docs: make connectors doc use same preparition [TD-14839] * docs: refine connectors doc [TD-14839] * docs: refine connectors doc [TD-14839] * docs: refine connector docs --- .../03-connector/03-connector.mdx | 2 +- docs-cn/14-reference/03-connector/csharp.mdx | 30 +++++-------------- docs-cn/14-reference/03-connector/go.mdx | 10 +++---- docs-cn/14-reference/03-connector/java.mdx | 7 +++-- docs-cn/14-reference/03-connector/node.mdx | 22 +++++++------- docs-cn/14-reference/03-connector/rust.mdx | 6 ++-- 6 files changed, 32 insertions(+), 45 deletions(-) diff --git a/docs-cn/14-reference/03-connector/03-connector.mdx b/docs-cn/14-reference/03-connector/03-connector.mdx index 68b958801f..bbd687e1e1 100644 --- a/docs-cn/14-reference/03-connector/03-connector.mdx +++ b/docs-cn/14-reference/03-connector/03-connector.mdx @@ -2,7 +2,7 @@ title: 连接器 --- -TDengine 提供了丰富的应用程序开发接口，其中官方连接器包括支持 C/C++、Java、Python、Go、Node.js、C# 等多种语言的连接器，支持使用原生接口（taosc）连接和 REST 接口（部分语言暂不支持）连接 TDengine 数据库，便于用户快速开发自己的应用。社区开发者也开发了多种非官方连接器，例如 Lua 连接器和 PHP 连接器。 +TDengine 提供了丰富的应用程序开发接口，为了便于用户快速开发自己的应用，TDengine 支持了多种编程语言的连接器，其中官方连接器包括支持 C/C++、Java、Python、Go、Node.js、C# 等语言的连接器。这些连接器支持使用原生接口（taosc）连接和 REST 接口（部分语言暂不支持）连接 TDengine 数据库。社区开发者也贡献了多个非官方连接器，例如 Lua 连接器和 PHP 连接器。 ![image-connector](/img/connector.png) diff --git a/docs-cn/14-reference/03-connector/csharp.mdx b/docs-cn/14-reference/03-connector/csharp.mdx index 619c99d592..2335ed8fb2 100644 --- a/docs-cn/14-reference/03-connector/csharp.mdx +++ b/docs-cn/14-reference/03-connector/csharp.mdx @@ -8,11 +8,11 @@ import Preparition from "./_preparition.mdx" ## 总体介绍 -TDengine.Connector 是 TDengine 提供的 C# 连接器。C# 语言开发人员可以通过它开发存取 TDengine 数据库的 C# 应用软件。连接器支持通过客户端驱动（taosc）建立本地连接 TDengine 服务端。进行查询、订阅、schemaless 接口、参数绑定接口等功能。 +`TDengine.Connector` 是 TDengine 提供的 C# 连接器。C# 语言开发人员可以通过它开发存取 TDengine 数据库的 C# 应用软件。连接器支持通过客户端驱动（taosc）建立本地连接 TDengine 数据库。进行数据写入、查询、订阅、schemaless 数据写入、参数绑定接口数据写入等功能。 -TDengine.Connector 目前暂未提供使用 REST 连接d的接口，用户可以参考 [RESTful APIs](https://docs.taosdata.com//reference/restful-api/) 文档自行编写。 +`TDengine.Connector` 目前暂未提供 REST 连接方式，用户可以参考 [RESTful APIs](https://docs.taosdata.com//reference/restful-api/) 文档自行编写。 -本文介绍如何在 Windows 或 Linux 环境中安装 TDengine.Connector，并通过 TDengine.Connector 连接 TDengine 数据库、进行数据查询、数据写入等基本操作。 +本文介绍如何在 Windows 或 Linux 环境中安装 `TDengine.Connector`，并通过 `TDengine.Connector` 连接 TDengine 数据库，进行数据写入、查询等基本操作。 ## 支持的平台 @@ -45,25 +45,11 @@ TDengine.Connector 目前暂未提供使用 REST 连接d的接口，用户可以 - ### 使用 dotnet CLI 安装 -使用 C# Connector 连接数据库前，需要具备以下条件： - -1. Linux 或 Windows 操作系统 -2. .Net 5.0 及以上运行时环境 -3. TDengine-client - -**注意**：使用 C# 连接器包时需要安装对应的客户端驱动。 - -- 在 Linux 系统中成功安装 TDengine 客户端之后，TDengine.Connector 依赖的本地客户端驱动 libtaos.so 文件会被自动拷贝至 /usr/lib/libtaos.so，该目录包含在 Linux 自动扫描路径上，无需单独指定。 -- 在 Windows 系统中成功安装 TDengine 客户端之后，TDengine.Connector 依赖的本地客户端驱动 taos.dll 文件会自动拷贝到系统默认搜索路径 C:/Windows/System32 下，同样无需单独指定。 - -**注意**：在 Windows 环境下开发时，需要安装 TDengine 对应的 [Windows 客户端](https://www.taosdata.com/cn/all-downloads/#TDengine-Windows-Client)，Linux 服务器安装完 TDengine 之后默认已安装 client，也可以单独安装 [Linux 客户端](/get-started/) 连接远程 TDengine Server。 - #### 使用 dotnet CLI 获取 C# 驱动 -可以在当前 .NET 项目的路径下，通过 dotnet 命令引用 Nuget 中发布的 TDengine.Connector 到当前项目。 +可以在当前 .NET 项目的路径下，通过 dotnet 命令引用 Nuget 中发布的 `TDengine.Connector` 到当前项目。 ``` bash dotnet add package TDengine.Connector @@ -71,12 +57,12 @@ dotnet add package TDengine.Connector #### 使用源码获取 C# 驱动 -可以下载 TDengine 的源码，直接引用最新版本的 TDengine.Connector库 +可以下载 TDengine 的源码，直接引用最新版本的 TDengine.Connector 库 ```bash git clone https://github.com/taosdata/TDengine.git cd TDengine/src/connector/C#/src/ -cp -r C#/src/TDengineDriver/ myProject +cp -r TDengineDriver/ myProject cd myProject dotnet add TDengineDriver/TDengineDriver.csproj @@ -145,7 +131,7 @@ namespace TDengineExample ### 第三方驱动 -Maikebing.Data.Taos 是一个 TDengine 的 ADO.NET 连接器，支持 Linux，Windows 平台。该连接器由社区贡献者`麦壳饼@@maikebing` 提供，具体请参考: +`Maikebing.Data.Taos` 是一个 TDengine 的 ADO.NET 连接器，支持 Linux，Windows 平台。该连接器由社区贡献者`麦壳饼@@maikebing` 提供，具体请参考: * 接口下载: * 用法说明: @@ -159,6 +145,6 @@ Maikebing.Data.Taos 是一个 TDengine 的 ADO.NET 连接器，支持 Linux，Wi * Unhandled exception. System.DllNotFoundException: Unable to load DLL 'taos' or one of its dependencies: 找不到指定的模块。 一般是因为程序没有找到依赖的客户端驱动。解决方法为：Windows 下可以将 `C:\TDengine\driver\taos.dll` 拷贝到 `C:\Windows\System32\ ` 目录下，Linux 下建立如下软链接 `ln -s /usr/local/taos/driver/libtaos.so.x.x.x.x /usr/lib/libtaos.so` 即可。 - + ## API 参考 [API 参考](https://docs.taosdata.com/api/connector-csharp/html/860d2ac1-dd52-39c9-e460-0829c4e5a40b.htm) diff --git a/docs-cn/14-reference/03-connector/go.mdx b/docs-cn/14-reference/03-connector/go.mdx index 954a17b862..03f8d608b3 100644 --- a/docs-cn/14-reference/03-connector/go.mdx +++ b/docs-cn/14-reference/03-connector/go.mdx @@ -8,13 +8,11 @@ import Preparition from "./_preparition.mdx" ## 总体介绍 -driver-go 是 TDengine 的官方 Go 语言连接器。Go 语言开发人员可以通过它开发存取 TDengine 数据库的应用软件。driver-go 实现了 Go [database/sql](https://golang.org/pkg/database/sql/) 包的接口，支持通过客户端驱动程序（taosc）原生连接 TDengine 服务端，支持数据写入、查询、订阅、schemaless 接口和参数绑定接口等功能。 +`driver-go` 是 TDengine 的官方 Go 语言连接器。Go 语言开发人员可以通过它开发存取 TDengine 数据库的应用软件。`driver-go` 实现了 Go 语言[ database/sql ](https://golang.org/pkg/database/sql/) 包的接口。`driver-go` 支持通过客户端驱动程序（taosc）原生连接 TDengine 服务端，支持数据写入、查询、订阅、schemaless 接口和参数绑定接口等功能。也支持使用 REST 连接 TDengine 数据库。REST 连接实现的功能特性集合和原生连接有少量不同。 -driver-go 也支持使用 REST 连接 TDengine 服务端。REST 连接实现的功能集合和原生连接有少量不同。 +本文介绍如何在 Windows 或 Linux 环境中安装 `driver-go`，并通过 `driver-go` 连接 TDengine 数据库、进行数据查询、数据写入等基本操作。 -本文介绍如何在 Windows 或 Linux 环境中安装 driver-go，并通过 driver-go 连接 TDengine 数据库、进行数据查询、数据写入等基本操作。 - -Go 连接器的源码托管在 github。项目名称：driver-go。欢迎 [贡献源码](https://github.com/taosdata/driver-go) 或 [报告问题](https://github.com/taosdata/driver-go/issues)。 +Go 连接器的源码托管在 GitHub。项目名称：driver-go。欢迎 [贡献源码](https://github.com/taosdata/driver-go) 或 [报告问题](https://github.com/taosdata/driver-go/issues)。 ## 支持的平台 @@ -315,7 +313,7 @@ stmt 查询，返回 `database/sql/driver` 包的 `Rows` 结构。 * `func (stmt *InsertStmt) Prepare(sql string) error` -预处理 sql 语句。 +预处理 SQL 语句。 * `func (stmt *InsertStmt) SetTableName(name string) error` diff --git a/docs-cn/14-reference/03-connector/java.mdx b/docs-cn/14-reference/03-connector/java.mdx index 9c37beb08f..4b3c1dce5c 100644 --- a/docs-cn/14-reference/03-connector/java.mdx +++ b/docs-cn/14-reference/03-connector/java.mdx @@ -9,9 +9,9 @@ import Preparition from "./_preparition.mdx" ## 总体介绍 -taos-jdbcdriver 是 TDengine 的官方 Java 语言连接器。Java 语言开发人员可以通过它开发存取 TDengine 数据库的应用软件。taos-jdbcdriver 实现了 JDBC driver 标准的接口。支持通过客户端驱动程序（taosc）原生连接 TDengine 服务端，支持数据写入、查询、订阅、schemaless 接口和参数绑定接口等功能。 +`taos-jdbcdriver` 是 TDengine 的官方 Java 语言连接器。Java 语言开发人员可以通过它开发存取 TDengine 数据库的应用软件。`taos-jdbcdriver` 实现了 JDBC driver 标准的接口。支持通过客户端驱动程序（taosc）原生连接 TDengine 服务端，支持数据写入、查询、订阅、schemaless 接口和参数绑定接口等功能。 -taos-jdbcdriver（2.0.18 和更高版本）也支持使用 REST 连接 TDengine 数据库。REST 连接实现的功能集合和原生连接有少量不同。 +`taos-jdbcdriver`（2.0.18 及更高版本）也支持使用 REST 连接 TDengine 数据库。REST 连接实现的功能集合和原生连接有少量不同。 ![tdengine-connector](/img/tdengine-jdbc-connector.png) @@ -19,8 +19,9 @@ taos-jdbcdriver（2.0.18 和更高版本）也支持使用 REST 连接 TDengine - JDBC 原生连接：Java 应用在物理节点 1（pnode1）上使用 JDBC 原生连接的 API ，直接调用客户端驱动（libtaos.so 或 taos.dll）的 API 将写入和查询请求发送到位于物理节点 2（pnode2）上的 taosd 实例。 - RESTful：应用将 SQL 发送给位于物理节点 2（pnode2）上的 REST 连接器，再调用客户端驱动 API。 -- JDBC-RESTful：Java 应用通过 JDBC-RESTful 的 API ，将 SQL 封装成一个 RESTful 请求，发送给物理节点 2 的 REST 连接器。 +- JDBC-RESTful：Java 应用通过 JDBC-RESTful 的 API ，将 SQL 封装成一个 REST 请求，发送给物理节点 2 的 REST 连接器。 +:::info TDengine 的 JDBC 驱动实现尽可能与关系型数据库驱动保持一致，但 TDengine 与关系对象型数据库的使用场景和技术特征存在差异，所以`taos-jdbcdriver` 与传统的 JDBC driver 也存在一定差异。在使用时需要注意以下几点： - TDengine 目前不支持针对单条数据记录的删除操作。 diff --git a/docs-cn/14-reference/03-connector/node.mdx b/docs-cn/14-reference/03-connector/node.mdx index c0b046f458..f513b46c80 100644 --- a/docs-cn/14-reference/03-connector/node.mdx +++ b/docs-cn/14-reference/03-connector/node.mdx @@ -8,7 +8,7 @@ import Preparition from "./_preparition.mdx" ## 总体介绍 -td2.0-connector 是 TDengine 的官方 Node.js 连接器。Node.js 开发人员可以通过它开发可以存取 TDengine 数据的应用软件。 +`td2.0-connector` 是 TDengine 的官方 Node.js 连接器。Node.js 开发人员可以通过它开发可以存取 TDengine 数据的应用软件。 ## 支持的平台 @@ -59,14 +59,14 @@ Node.js 连接器支持的系统有： - 应用驱动安装请参考[安装连接器驱动步骤](/reference/connector/#安装客户端驱动)。 -我们使用[node-gyp](https://github.com/nodejs/node-gyp)和 TDengine 服务端进行交互。安装 Node.js 连接器之前，还需要根据具体操作系统来安装下文提到的一些依赖工具。如果要安装的是 RESTful 连接器则可以跳过以下步骤，直接只用 npm 安装。 +我们使用[node-gyp](https://github.com/nodejs/node-gyp)和 TDengine 服务端进行交互。安装 Node.js 连接器之前，还需要根据具体操作系统来安装下文提到的一些依赖工具。如果要安装的是 REST 连接器则可以跳过以下步骤，直接只用 npm 安装。 ### Linux - `python` (建议`v2.7` , `v3.x.x` 目前还不支持) -- `node` 2.0.6 支持 >=v12.8.0 <= v12.9.1 || >=v10.20.0 <= v10.9.0 ；2.0.5 及更早版本支持 v10.x 版本，其他版本可能存在包兼容性的问题。 +- `td2.0-connector` 2.0.6 支持 Node.js LTS v10.9.0 或更高版本, Node.js LTS v12.8.0 或更高版本；2.0.5 及更早版本支持 Node.js LTS v10.x 版本。其他版本可能存在包兼容性的问题 - `make` -- c 语言编译器比如[GCC](https://gcc.gnu.org) +- C 语言编译器，[GCC](https://gcc.gnu.org) v4.8.5 或更高版本 ### Windows @@ -82,7 +82,7 @@ Node.js 连接器支持的系统有： - 安装 [Python](https://www.python.org/downloads/) 2.7(`v3.x.x` 暂不支持) 并执行 `npm config set python python2.7` - 进入`cmd`命令行界面，`npm config set msvs_version 2017` -如果以上步骤不能成功执行，可以参考微软的 Node.js 用户手册[Microsoft's Node.js Guidelines for Windows](https://github.com/Microsoft/nodejs-guidelines/blob/master/windows-environment.md#compiling-native-addon-modules)。 +参考微软的 Node.js 用户手册[Microsoft's Node.js Guidelines for Windows](https://github.com/Microsoft/nodejs-guidelines/blob/master/windows-environment.md#compiling-native-addon-modules)。 如果在 Windows 10 ARM 上使用 ARM64 Node.js，还需添加 "Visual C++ compilers and libraries for ARM64" 和 "Visual C++ ATL for ARM64"。 @@ -94,7 +94,7 @@ Node.js 连接器支持的系统有： npm install td2.0-connector ``` -- 安装 RESTful 连接器 +- 安装 REST 连接器 ```bash npm i td2.0-rest-connector @@ -116,7 +116,7 @@ npm install td2.0-connector node nodejsChecker.js host=localhost ``` -- 执行以上步骤后，在命令行会输出 nodejs 连接 TDengine 实例，并执行简答插入和查询的结果。 +- 执行以上步骤后，在命令行会输出 nodejs 连接 TDengine 实例，并执行简单插入和查询的结果。 ## 建立连接 @@ -134,7 +134,7 @@ var cursor = conn.cursor(); // Initializing a new cursor conn.close(); ``` -### 建立RESTful连接 +### 建立 REST 连接 安装并引用 `td2.0-rest-connector` 包。 @@ -154,7 +154,7 @@ let cursor = conn.cursor(); ## 使用示例 | 示例程序 | 示例程序描述 | |-----------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------| -| [connection](https://github.com/taosdata/TDengine/blob/develop/src/connector/nodejs/examples/cursorClose.js) | 建立连接的示例。 | +| [connection](https://github.com/taosdata/TDengine/blob/develop/src/connector/nodejs/examples/cursorClose.js) | 建立连接的示例。 | | [stmtBindBatch](https://github.com/taosdata/TDengine/blob/develop/src/connector/nodejs/examples/stmtBindParamBatchSample.js) | 绑定多行参数插入的示例。 | | [stmtBind](https://github.com/taosdata/TDengine/blob/develop/src/connector/nodejs/examples/stmtBindParamSample.js) | 一行一行绑定参数插入的示例。 | | [stmtBindSingleParamBatch](https://github.com/taosdata/TDengine/blob/develop/src/connector/nodejs/examples/stmtBindSingleParamBatchSample.js) | 按列绑定参数插入的示例。 | @@ -165,7 +165,7 @@ let cursor = conn.cursor(); | [schemless insert](https://github.com/taosdata/TDengine/blob/develop/src/connector/nodejs/examples/testSchemalessInsert.js) | schemless 插入的示例。 | | [subscribe](https://github.com/taosdata/TDengine/blob/develop/src/connector/nodejs/examples/testSubscribe.js) | 订阅的使用示例。 | | [asyncQuery](https://github.com/taosdata/TDengine/blob/develop/src/connector/nodejs/examples/tset.js) | 异步查询的使用示例。 | -| [RESTful](https://github.com/taosdata/TDengine/tree/develop/src/connector/TypeScript-REST/example) | RESTful 连接的 TypeScript 使用示例。 | +| [REST](https://github.com/taosdata/TDengine/tree/develop/src/connector/TypeScript-REST/example) | 使用 REST 连接的 TypeScript 使用示例。| ## 使用限制 @@ -189,7 +189,7 @@ Node.js 连接器的使用参见[视频教程](https://www.taosdata.com/blog/202 ## 常见问题（optional) -1. 使用 RESTful 连接需要启动 taosadapter。 +1. 使用 REST 连接需要启动 taosadapter。 ``` bash sudo systemctl start taosadapter diff --git a/docs-cn/14-reference/03-connector/rust.mdx b/docs-cn/14-reference/03-connector/rust.mdx index e313cc1b38..83957b6131 100644 --- a/docs-cn/14-reference/03-connector/rust.mdx +++ b/docs-cn/14-reference/03-connector/rust.mdx @@ -8,7 +8,7 @@ import Preparition from "./_preparition.mdx" [![Crates.io](https://img.shields.io/crates/v/libtaos)](https://crates.io/crates/libtaos) ![Crates.io](https://img.shields.io/crates/d/libtaos) [![docs.rs](https://img.shields.io/docsrs/libtaos)](https://docs.rs/libtaos) -libtaos 是 TDengine 的官方 Rust 语言连接器。Rust 语言开发人员可以通过它开发存取 TDengine 数据库的应用软件。libtaos 使用不同的 features 提供对通过客户端驱动程序（taosc）原生连接和使用 REST 连接 TDengine 服务端的。以下是可使用的特性列表： +`libtaos` 是 TDengine 的官方 Rust 语言连接器。Rust 语言开发人员可以通过它开发存取 TDengine 数据库的应用软件。`libtaos` 使用不同的 “特性（Rust Cargo 包管理关键字 features）” 提供对通过客户端驱动程序（taosc）原生连接和使用 REST 连接 TDengine 数据库。以下是可使用的特性列表： | 启用特性 | 支持平台 | 说明 | | -------- | --------------------- | ----------------------------------------------------------------- | @@ -16,7 +16,9 @@ libtaos 是 TDengine 的官方 Rust 语言连接器。Rust 语言开发人员可 | rest | Windows, Linux, macOS | 使用 HTTP REST API 接口（rest），适用于全平台 | | (+)r2d2 | - | 使用 [r2d2] 提供的连接池接口，需要与 default 或 rest 特性配合使用 | -*NOTE: Rust 连接器仍然在快速开发中，1.0 之前无法保证其向后兼容，请使用时注意版本及对应的文档。* +:::warning + +Rust 连接器仍然在快速开发中，1.0 之前无法保证其向后兼容，请使用时注意版本及对应的文档。* ## 版本支持 -- GitLab