Skip to content

T
TDengine

taosdata / TDengine
1 年多 前同步成功

通知 1187
Star 22018
Fork 4786
T
TDengine
未验证 提交 b082e26a 编写于 作者: sangshuduo's avatar sangshuduo 提交者： GitHub
浏览文件
操作

docs: translate node and rest (#12519) 

* docs: connector in English

[TD-15544]

* docs: connector doc in English

[TD-15544]

* fix format issues

* fix format issues

* translate rest and node in English
上级 df74ee27
隐藏空白更改
内联 并排
Showing with 171 addition and 171 deletion
docs-en/14-reference/02-rest-api/02-rest-api.mdx
浏览文件 @ b082e26a
......@@ -2,28 +2,28 @@
title: REST API
---
为支持各种不同类型平台的开发，TDengine 提供符合 REST 设计标准的 API，即 REST API。为最大程度降低学习成本，不同于其他数据库 REST API 的设计方法，TDengine 直接通过 HTTP POST 请求 BODY 中包含的 SQL 语句来操作数据库，仅需要一个 URL。REST 连接器的使用参见[视频教程](https://www.taosdata.com/blog/2020/11/11/1965.html)。
TDengine provides an API that conforms to REST design standards to support development on various platforms, i.e., the REST API. To minimize learning costs, and unlike other databases' REST API design approaches, TDengine operates on databases directly through HTTP POST requests for SQL statements contained in the BODY, requiring only a URL. See the [video tutorial](https://www.taosdata.com/blog/2020/11/11/1965.html) to use the REST connector.
注意：与原生连接器的一个区别是，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。）
Note: One difference from the native connector is that the RESTful interface is stateless, so the `USE db_name` directive has no effect. All references to table names and super table names need to be specified with a database name prefix. (Starting with version 2.2.0.0, RESTful supports specifying db_name in the RESTful URL, so if the database name prefix is not specified in the SQL statement, the db_name specified in the URL will be used. (db_name.)
## 安装
## Installation
RESTful 接口不依赖于任何 TDengine 的库，因此客户端不需要安装任何 TDengine 的库，只要客户端的开发语言支持 HTTP 协议即可。
The RESTful interface does not rely on any TDengine libraries, so the client does not need to install any TDengine libraries. The client's development language supports the HTTP protocol.
## 验证
## Verification
在已经安装 TDengine 服务器端的情况下，可以按照如下方式进行验证。
If the TDengine server side is already installed, it can be verified as follows:
下面以 Ubuntu 环境中使用 curl 工具（确认已经安装）来验证 RESTful 接口的正常。
The following is an Ubuntu environment using the curl tool (to confirm that it is installed) to verify that the RESTful interface is working.
下面示例是列出所有的数据库，请把 h1.taosdata.com 和 6041（缺省值）替换为实际运行的 TDengine 服务 fqdn 和端口号：
The following example lists all databases, replacing h1.taosdata.com and 6041 (the default) with the actual running TDengine service FQDN and port number.
```html
curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'show databases;'
h1.taosdata.com:6041/rest/sql
```
返回值结果如下表示验证通过：
The following return value results indicate that the validation passed.
```json
{
......@@ -72,111 +72,111 @@ h1.taosdata.com:6041/rest/sql
}
```
## HTTP 请求格式
## HTTP request URL format
```
http://<fqdn>:<port>/rest/sql/[db_name]
```
参数说明：
Parameter Description.
- fqnd: 集群中的任一台主机 FQDN 或 IP 地址
- port: 配置文件中 httpPort 配置项，缺省为 6041
- db_name: 可选参数，指定本次所执行的 SQL 语句的默认数据库库名。（从 2.2.0.0 版本开始支持）
- fqnd: FQDN or IP address of any host in the cluster
- port: httpPort configuration item in the configuration file, default is 6041
- db_name: Optional parameter that specifies the default database name for the executed SQL statement. (supported since version 2.2.0.0)
例如：http://h1.taos.com:6041/rest/sql/test 是指向地址为 h1.taos.com:6041 的 url，并将默认使用的数据库库名设置为 test。
For example, http://h1.taos.com:6041/rest/sql/test is a URL to h1.taos.com:6041 and sets the default database name to test.
HTTP 请求的 Header 里需带有身份认证信息，TDengine 支持 Basic 认证与自定义认证两种机制，后续版本将提供标准安全的数字签名机制来做身份验证。
TDengine supports both Basic authentication and custom authentication mechanisms, and subsequent versions will provide a standard secure digital signature mechanism for authentication.
- 自定义身份认证信息如下所示（token 稍后介绍）
- The custom authentication information is as follows (Let's introduce token later)
```
Authorization: Taosd <TOKEN>
```
- Basic 身份认证信息如下所示
- Basic authentication information is shown below
```
Authorization: Basic <TOKEN>
```
HTTP 请求的 BODY 里就是一个完整的 SQL 语句，SQL 语句中的数据表应提供数据库前缀，例如 \<db_name>.\<tb_name>。如果表名不带数据库前缀，又没有在 url 中指定数据库名的话，系统会返回错误。因为 HTTP 模块只是一个简单的转发，没有当前 DB 的概念。
The HTTP request's BODY is a complete SQL statement, and the data table in the SQL statement should be provided with a database prefix, e.g., \<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 because the HTTP module is a simple forwarder and has no concept of the current DB.
使用 curl 通过自定义身份认证方式来发起一个 HTTP Request，语法如下：
Use curl to initiate an HTTP Request with a custom authentication method, with the following syntax.
```bash
curl -H 'Authorization: Basic <TOKEN>' -d '<SQL>' <ip>:<PORT>/rest/sql/[db_name]
```
或者
Or
```bash
curl -u username:password -d '<SQL>' <ip>:<PORT>/rest/sql/[db_name]
```
其中，`TOKEN` 为 `{username}:{password}` 经过 Base64 编码之后的字符串，例如 `root:taosdata` 编码后为 `cm9vdDp0YW9zZGF0YQ==`
where `TOKEN` is the string after Base64 encoding of `{username}:{password}`, e.g. `root:taosdata` is encoded as `cm9vdDp0YW9zZGF0YQ==`
## HTTP 返回格式
## HTTP Return Format
返回值为 JSON 格式，如下:
The return value is in JSON format, as follows:
```json
{
"status": "succ",
"head": ["ts","current", …],
"column_meta": [["ts",9,8],["current",6,4], …],
"head": ["ts", "current", ...],
"column_meta": [["ts",9,8],["current",6,4], ...],
"data": [
["2018-10-03 14:38:05.000", 10.3, …],
["2018-10-03 14:38:15.000", 12.6, …]
["2018-10-03 14:38:05.000", 10.3, ...],
["2018-10-03 14:38:15.000", 12.6, ...]
],
"rows": 2
}
```
说明：
Description.
- status: 告知操作结果是成功还是失败。
- head: 表的定义，如果不返回结果集，则仅有一列 “affected_rows”。（从 2.0.17.0 版本开始，建议不要依赖 head 返回值来判断数据列类型，而推荐使用 column_meta。在未来版本中，有可能会从返回值中去掉 head 这一项。）
- column_meta: 从 2.0.17.0 版本开始，返回值中增加这一项来说明 data 里每一列的数据类型。具体每个列会用三个值来说明，分别为：列名、列类型、类型长度。例如`["current",6,4]`表示列名为“current”；列类型为 6，也即 float 类型；类型长度为 4，也即对应 4 个字节表示的 float。如果列类型为 binary 或 nchar，则类型长度表示该列最多可以保存的内容长度，而不是本次返回值中的具体数据长度。当列类型是 nchar 的时候，其类型长度表示可以保存的 unicode 字符数量，而不是 bytes。
- data: 具体返回的数据，一行一行的呈现，如果不返回结果集，那么就仅有 [[affected_rows]]。data 中每一行的数据列顺序，与 column_meta 中描述数据列的顺序完全一致。
- rows: 表明总共多少行数据。
- status: tell if the operation result is success or failure.
- head: the definition of the table, or just one column "affected_rows" if no result set is returned. (As of version 2.0.17.0, it is recommended not to rely on the head return value to determine the data column type but rather use column_meta. In future versions, the head item may be removed from the return value.)
- column_meta: this item is added to the return value to indicate the data type of each column in the data with version 2.0.17.0 and later versions. Each column is described by three values: column name, column type, and type length. For example, `["current",6,4]` means that the column name is "current", the column type is 6, which is the float type, and the type length is 4, which is the float type with 4 bytes. If the column type is binary or nchar, the type length indicates the maximum length of content stored in the column, not the length of the specific data in this return value. When the column type is nchar, the type length indicates the number of Unicode characters that can be saved, not bytes.
- data: The exact data returned, presented row by row, or just [[affected_rows]] if no result set is returned. The order of the data columns in each row of data is the same as that of the data columns described in column_meta.
- rows: Indicates how many rows of data there are.
column_meta 中的列类型说明：
The column types in column_meta are described as follows:
- 1：BOOL
- 2：TINYINT
- 3：SMALLINT
- 4：INT
- 5：BIGINT
- 6：FLOAT
- 7：DOUBLE
- 8：BINARY
- 9：TIMESTAMP
- 10：NCHAR
- 1:BOOL
- 2:TINYINT
- 3:SMALLINT
- 4:INT
- 5:BIGINT
- 6:FLOAT
- 7:DOUBLE
- 8:BINARY
- 9:TIMESTAMP
- 10:NCHAR
## 自定义授权码
## Custom Authorization Code
HTTP 请求中需要带有授权码 `<TOKEN>`，用于身份识别。授权码通常由管理员提供，可简单的通过发送 `HTTP GET` 请求来获取授权码，操作如下：
HTTP requests require an authorization code `<TOKEN>` for identification purposes. The administrator usually provides the authorization code, and it can be obtained simply by sending an ``HTTP GET`` request as follows:
```bash
curl http://<fqnd>:<port>/rest/login/<username>/<password>
```
其中，`fqdn` 是 TDengine 数据库的 fqdn 或 ip 地址，port 是 TDengine 服务的端口号，`username` 为数据库用户名，`password` 为数据库密码，返回值为 `JSON` 格式，各字段含义如下：
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. `password` is the database password. The return value is in `JSON` format, and the meaning of each field is as follows.
- status：请求结果的标志位
- status: flag bit of the request result
- code：返回值代码
- code: return value code
- desc：授权码
- desc: authorization code
获取授权码示例：
Example of getting authorization code.
```bash
curl http://192.168.0.1:6041/rest/login/root/taosdata
```
返回值：
Response body:
```json
{
......@@ -186,15 +186,15 @@ curl http://192.168.0.1:6041/rest/login/root/taosdata
}
```
## 使用示例
## For example
- 在 demo 库里查询表 d1001 的所有记录：
- query all records from table d1001 of database demo
```bash
curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'select * from demo.d1001' 192.168.0.1:6041/rest/sql
```
返回值：
Response body:
```json
{
......@@ -214,13 +214,13 @@ curl http://192.168.0.1:6041/rest/login/root/taosdata
}
```
- 创建库 demo：
- Create database demo:
```bash
curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'create database demo' 192.168.0.1:6041/rest/sql
```
返回值：
Response body:
```json
{
......@@ -232,17 +232,17 @@ curl http://192.168.0.1:6041/rest/login/root/taosdata
}
```
## 其他用法
## Other Uses
### 结果集采用 Unix 时间戳
### Unix timestamps for result sets
HTTP 请求 URL 采用 `sqlt` 时，返回结果集的时间戳将采用 Unix 时间戳格式表示，例如
When the HTTP request URL uses `sqlt`, the timestamp of the returned result set will be in Unix timestamp format, for example:
```bash
curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'select * from demo.d1001' 192.168.0.1:6041/rest/sqlt
```
返回值：
Response body:
```json
{
......@@ -262,15 +262,15 @@ curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'select * from demo.d1001
}
```
### 结果集采用 UTC 时间字符串
### UTC format for the result set
HTTP 请求 URL 采用 `sqlutc` 时，返回结果集的时间戳将采用 UTC 时间字符串表示，例如
When the HTTP request URL uses `sqlutc`, the timestamp of the returned result set will be expressed as a UTC format, for example:
```bash
curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'select * from demo.t1' 192.168.0.1:6041/rest/sqlutc
```
返回值：
Respones body:
```json
{
......@@ -290,18 +290,18 @@ HTTP 请求 URL 采用 `sqlutc` 时，返回结果集的时间戳将采用 UTC
}
```
## 重要配置项
## Important configuration items
下面仅列出一些与 RESTful 接口有关的配置参数，其他系统参数请看配置文件里的说明。
Only some configuration parameters related to the RESTful interface are listed below. Please see the description in the configuration file for other system parameters.
- 对外提供 RESTful 服务的端口号，默认绑定到 6041（实际取值是 serverPort + 11，因此可以通过修改 serverPort 参数的设置来修改）。
- httpMaxThreads: 启动的线程数量，默认为 2（2.0.17.0 版本开始，默认值改为 CPU 核数的一半向下取整）。
- restfulRowLimit: 返回结果集（JSON 格式）的最大条数，默认值为 10240。
- httpEnableCompress: 是否支持压缩，默认不支持，目前 TDengine 仅支持 gzip 压缩格式。
- httpDebugFlag: 日志开关，默认 131。131：仅错误和报警信息，135：调试信息，143：非常详细的调试信息，默认 131。
- httpDbNameMandatory: 是否必须在 RESTful url 中指定默认的数据库名。默认为 0，即关闭此检查。如果设置为 1，那么每个 RESTful url 中都必须设置一个默认数据库名，否则无论此时执行的 SQL 语句是否需要指定数据库，都会返回一个执行错误，拒绝执行此 SQL 语句。
- The port number of the external RESTful service is bound to 6041 by default (the actual value is serverPort + 11, so it can be changed by modifying the setting of the serverPort parameter).
- httpMaxThreads: the number of threads to start, default is 2 (the default value is rounded down to half of the CPU cores with version 2.0.17.0 and later versions).
- restfulRowLimit: the maximum number of result sets (in JSON format) to return. The default value is 10240.
- httpEnableCompress: whether to support compression, the default is not supported. Currently, TDengine only supports the gzip compression format.
- httpDebugFlag: logging switch, default 131. 131: error and alarm messages only, 135: debug messages, 143: very detailed debug messages, default 131.
- httpDbNameMandatory: users must specify the default database name in the RESTful URL. The default is 0, which turns off this check. If set to 1, users must put a default database name in every RESTful URL. Otherwise, it will return an execution error and reject this SQL statement, regardless of whether the SQL statement executed at this time requires a specified database.
:::note
如果使用 taosd 提供的 REST API, 那么以上配置需要写在 taosd 的配置文件 taos.cfg 中。如果使用 taosAdaper 提供的 REST API, 那么需要参考 taosAdaper [对应的配置方法](/reference/taosadapter/)。
If you are using the REST API provided by taosd, you should write the above configuration in taosd's configuration file taos.cfg. If you use the REST API of taosAdaper, you need to refer to taosAdaper [corresponding configuration method](/reference/taosadapter/).
:::
docs-en/14-reference/03-connector/node.mdx
浏览文件 @ b082e26a
......@@ -16,86 +16,86 @@ import NodeOpenTSDBJson from "../../04-develop/03-insert-data/_js_opts_json.mdx"
import NodeQuery from "../../04-develop/04-query-data/_js.mdx";
import NodeAsyncQuery from "../../04-develop/04-query-data/_js_async.mdx";
`td2.0-connector` 和 `td2.0-rest-connector` 是 TDengine 的官方 Node.js 语言连接器。Node.js 开发人员可以通过它开发可以存取 TDengine 集群数据的应用软件。
`td2.0-connector` and `td2.0-rest-connector` are the official Node.js language connectors for TDengine, through which Node.js developers can develop applications that can access TDengine cluster data.
`td2.0-connector` 是**原生连接器**，它通过 TDengine 客户端驱动程序（taosc）连接 TDengine 运行实例，支持数据写入、查询、订阅、schemaless 接口和参数绑定接口等功能。`td2.0-rest-connector` 是 **REST 连接器**，它通过 taosAdapter 提供的 REST 接口连接 TDengine 的运行实例。REST 连接器可以在任何平台运行，但性能略为下降，接口实现的功能特性集合和原生接口有少量不同。
`td2.0-connector` is a **native connector** that connects to TDengine runtime instances via the TDengine client driver (taosc) and supports data writing, querying, subscriptions, schemaless interface, and parameter binding interface. The `td2.0-rest-connector` is a **REST connector** that connects to TDengine runtime instances via the REST interface provided by taosAdapter. The REST connector can run on any platform, but performance is slightly degraded, and the interface implements a somewhat different set of functional features than the native interface.
Node.js 连接器源码托管在 [GitHub](https://github.com/taosdata/taos-connector-node)。
The Node.js connector source code is hosted on [GitHub](https://github.com/taosdata/taos-connector-node).
## 支持的平台
## Supported Platforms
原生连接器支持的平台和 TDengine 客户端驱动支持的平台一致。
REST 连接器支持所有能运行 Node.js 的平台。
The platforms supported by the native connector are the same as those supported by the TDengine client driver.
The REST connector supports all platforms that can run Node.js.
## 版本支持
## Version support
请参考[版本支持列表](/reference/connector#版本支持)
Please refer to [version support list](/reference/connector#version support)
## 支持的功能特性
## Supported features
### 原生连接器
### Native connectors
1. 连接管理
2. 普通查询
3. 连续查询
4. 参数绑定
5. 订阅功能
1. connection management
2. general query
3. continuous query
4. parameter binding
5. subscription function
6. Schemaless
### REST 连接器
### REST Connector
1. 连接管理
2. 普通查询
3. 连续查询
1. connection management
2. general queries
3. Continuous query
## 安装步骤
## Installation steps
### 安装前准备
### Pre-installation
- 安装 Node.js 开发环境
- 如果使用 REST 连接器，跳过此步。但如果使用原生连接器，请安装 TDengine 客户端驱动，具体步骤请参考[安装客户端驱动](/reference/connector#安装客户端驱动)。我们使用 [node-gyp](https://github.com/nodejs/node-gyp) 和 TDengine 实例进行交互，还需要根据具体操作系统来安装下文提到的一些依赖工具。
- Install the Node.js development environment
- If you are using the REST connector, skip this step. However, if you use the native connector, please install the TDengine client driver. Please refer to [install client driver](/reference/connector#install-client-driver) for more details. We use [node-gyp](https://github.com/nodejs/node-gyp) to interact with TDengine instances and also need to install some dependencies mentioned below depending on the specific OS.
<Tabs defaultValue="Linux">
<TabItem value="Linux" label="Linux 系统安装依赖工具">
<TabItem value="Linux" label="Linux system installation dependencies">
- `python` (建议`v2.7` , `v3.x.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 版本。其他版本可能存在包兼容性的问题
- `python` (recommended for `v2.7` , `v3.x.x` currently not supported)
- `td2.0-connector` 2.0.6 supports Node.js LTS v10.9.0 or later, Node.js LTS v12.8.0 or later; 2.0.5 and earlier support Node.js LTS v10.x versions. Other versions may have package compatibility issues
- `make`
- C 语言编译器，[GCC](https://gcc.gnu.org) v4.8.5 或更高版本
- C compiler, [GCC](https://gcc.gnu.org) v4.8.5 or higher
</TabItem>
<TabItem value="Windows" label="Windows 系统安装依赖工具">
<TabItem value="Windows" label="Windows system installation dependencies">
- 安装方法 1
- Installation method 1
使用微软的[ windows-build-tools ](https://github.com/felixrieseberg/windows-build-tools)在`cmd` 命令行界面执行`npm install --global --production windows-build-tools` 即可安装所有的必备工具。
Use Microsoft's [ windows-build-tools ](https://github.com/felixrieseberg/windows-build-tools) to execute `npm install --global --production` from the `cmd` command-line interface to install all the necessary tools.
- 安装方法 2
- Installation method 2
手动安装以下工具：
Manually install the following tools.
- 安装 Visual Studio 相关：[Visual Studio Build 工具](https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=BuildTools) 或者 [Visual Studio 2017 Community](https://visualstudio.microsoft.com/pl/thank-you-downloading-visual-studio/?sku=Community)
- 安装 [Python](https://www.python.org/downloads/) 2.7(`v3.x.x` 暂不支持) 并执行 `npm config set python python2.7`
- 进入`cmd`命令行界面，`npm config set msvs_version 2017`
- Install Visual Studio related: [Visual Studio Build Tools](https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=BuildTools) or [ Visual Studio 2017 Community](https://visualstudio.microsoft.com/pl/thank-you-downloading-visual-studio/?sku=Community)
- Install [Python](https://www.python.org/downloads/) 2.7 (`v3.x.x` is not supported) and execute `npm config set python python2.7`.
- Go to the `cmd` command line interface, `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)。
Refer to Microsoft's Node.js User Manual [ 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"。
If using ARM64 Node.js on Windows 10 ARM, you must add "Visual C++ compilers and libraries for ARM64" and "Visual C++ ATL for ARM64".
</TabItem>
</Tabs>
### 使用 npm 安装
### Install via npm
<Tabs defaultValue="install_native">
<TabItem value="install_native" label="安装原生连接器">
<TabItem value="install_native" label="Install native connector">
```bash
npm install td2.0-connector
```
</TabItem>
<TabItem value="install_rest" label="安装 REST 连接器">
<TabItem value="install_rest" label="Install REST connector">
```bash
npm i td2.0-rest-connector
......@@ -104,15 +104,15 @@ npm i td2.0-rest-connector
</TabItem>
</Tabs>
### 安装验证
### Installation verification
在安装好 TDengine 客户端后，使用 nodejsChecker.js 程序能够验证当前环境是否支持 Node.js 方式访问 TDengine。
After installing the TDengine client, use the nodejsChecker.js program to verify that the current environment supports Node.js access to TDengine.
验证方法：
Validation method.
- 新建安装验证目录，例如：`~/tdengine-test`，下载 GitHub 上 [nodejsChecker.js 源代码](https://github.com/taosdata/TDengine/tree/develop/examples/nodejs/nodejsChecker.js)到本地。
- Create a new installation verification directory, e.g. `~/tdengine-test`, and download the [nodejsChecker.js source code](https://github.com/taosdata/TDengine/tree/develop/examples/nodejs/) from GitHub. nodejsChecker.js) to local.
- 在命令行中执行以下命令。
- Execute the following command from the command line.
```bash
npm init -y
......@@ -120,16 +120,16 @@ npm install td2.0-connector
node nodejsChecker.js host=localhost
```
- 执行以上步骤后，在命令行会输出 nodejsChecker.js 连接 TDengine 实例，并执行简单插入和查询的结果。
- After executing the above steps, the command line will output the result of nodejsChecker.js connecting to the TDengine instance and performing a simple insert and query.
## 建立连接
## Establishing a connection
请选择使用一种连接器。
Please choose to use one of the connectors.
<Tabs defaultValue="native">
<TabItem value="native" label="原生连接">
<TabItem value="native" label="Native connection">
安装并引用 `td2.0-connector` 包。
Install and refer to `td2.0-connector` package:
```javascript
//A cursor also needs to be initialized in order to interact with TDengine from Node.js.
......@@ -150,7 +150,7 @@ conn.close();
</TabItem>
<TabItem value="rest" label="REST 连接">
安装并引用 `td2.0-rest-connector` 包。
Install and refer to `td2.0-rest-connector`package:
```javascript
//A cursor also needs to be initialized in order to interact with TDengine from Node.js.
......@@ -167,93 +167,93 @@ let cursor = conn.cursor();
</TabItem>
</Tabs>
## 使用示例
## Usage examples
### 写入数据
### Write data
#### SQL 写入
#### SQL Writing
<NodeInsert />
#### InfluxDB 行协议写入
#### InfluxDB line protocol writing
<NodeInfluxLine />
#### OpenTSDB Telnet 行协议写入
#### OpenTSDB Telnet line protocol writing
<NodeOpenTSDBTelnet />
#### OpenTSDB JSON 行协议写入
#### OpenTSDB JSON line protocol writing
<NodeOpenTSDBJson />
### 查询数据
### Query data
#### 同步查询
#### Synchronous queries
<NodeQuery />
#### 异步查询
#### asynchronous query
<NodeAsyncQuery />
## 更多示例程序
## More Sample Programs
| 示例程序 | 示例程序描述 |
| ------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------- |
| [connection](https://github.com/taosdata/taos-connector-node/tree/develop/nodejs/examples/cursorClose.js) | 建立连接的示例。 |
| [stmtBindBatch](https://github.com/taosdata/taos-connector-node/tree/develop/nodejs/examples/stmtBindParamBatchSample.js) | 绑定多行参数插入的示例。 |
| [stmtBind](https://github.com/taosdata/taos-connector-node/tree/develop/nodejs/examples/stmtBindParamSample.js) | 一行一行绑定参数插入的示例。 |
| [stmtBindSingleParamBatch](https://github.com/taosdata/taos-connector-node/tree/develop/nodejs/examples/stmtBindSingleParamBatchSample.js) | 按列绑定参数插入的示例。 |
| [stmtUseResult](https://github.com/taosdata/taos-connector-node/tree/develop/nodejs/examples/stmtUseResultSample.js) | 绑定参数查询的示例。 |
| [json tag](https://github.com/taosdata/taos-connector-node/tree/develop/nodejs/examples/testJsonTag.js) | Json tag 的使用示例。 |
| [Nanosecond](https://github.com/taosdata/taos-connector-node/tree/develop/nodejs/examples/testNanoseconds.js) | 时间戳为纳秒精度的使用的示例。 |
| [Microsecond](https://github.com/taosdata/taos-connector-node/tree/develop/nodejs/examples/testMicroseconds.js) | 时间戳为微秒精度的使用的示例。 |
| [schemless insert](https://github.com/taosdata/taos-connector-node/tree/develop/nodejs/examples/testSchemalessInsert.js) | schemless 插入的示例。 |
| [subscribe](https://github.com/taosdata/taos-connector-node/tree/develop/nodejs/examples/testSubscribe.js) | 订阅的使用示例。 |
| [asyncQuery](https://github.com/taosdata/taos-connector-node/tree/develop/nodejs/examples/tset.js) | 异步查询的使用示例。 |
| [REST](https://github.com/taosdata/taos-connector-node/blob/develop/typescript-rest/example/example.ts) | 使用 REST 连接的 TypeScript 使用示例。 |
| Sample Programs | Sample Program Description |
| --------------------------------------------------------------------------------------------------------------------------------- --------- | -------------------------------------- |
| [connection](https://github.com/taosdata/taos-connector-node/tree/develop/nodejs/examples/cursorClose.js) | Example of establishing a connection. | [stmtBind]()
| [stmtBindBatch](https://github.com/taosdata/taos-connector-node/tree/develop/nodejs/examples/stmtBindParamBatchSample.js) | Example of binding a multi-line parameter Example of inserting. | [stmtBindBatch]()
| [stmtBind](https://github.com/taosdata/taos-connector-node/tree/develop/nodejs/examples/stmtBindParamSample.js) | Example of a line-by-line bind parameter insertion. | [stmtBind]()
| [stmtBindSingleParamBatch](https://github.com/taosdata/taos-connector-node/tree/develop/nodejs/examples/) stmtBindSingleParamBatchSample.js) | Example of binding parameters by column. |
| [stmtUseResult](https://github.com/taosdata/taos-connector-node/tree/develop/nodejs/examples/stmtUseResultSample.js) | Example of a bound parameter query. | [stmtUseResult]()
| [json tag](https://github.com/taosdata/taos-connector-node/tree/develop/nodejs/examples/testJsonTag.js) | Example of using Json tag. | [json tag]()
| [Nanosecond](https://github.com/taosdata/taos-connector-node/tree/develop/nodejs/examples/testNanoseconds.js) | An example of using timestamps with nanosecond precision. | [Nanosecond]()
| [Microsecond](https://github.com/taosdata/taos-connector-node/tree/develop/nodejs/examples/testMicroseconds.js) | Example of using microsecond timestamp. | [schemless insert]()
| [schemless insert](https://github.com/taosdata/taos-connector-node/tree/develop/nodejs/examples/testSchemalessInsert.js) | schemless Example of a schemless insert. | [schemless insert]()
| [subscribe](https://github.com/taosdata/taos-connector-node/tree/develop/nodejs/examples/testSubscribe.js) | Example of using subscribe. | [schemless insert]()
| [asyncQuery](https://github.com/taosdata/taos-connector-node/tree/develop/nodejs/examples/tset.js) | An example of using asynchronous queries. | [asyncQuery]()
| [REST](https://github.com/taosdata/taos-connector-node/blob/develop/typescript-rest/example/example.ts) | An example of using TypeScript with REST connections. | [REST]()
## 使用限制
## Usage restrictions
Node.js 连接器 >= v2.0.6 目前支持 node 的版本为：支持 >=v12.8.0 <= v12.9.1 || >=v10.20.0 <= v10.9.0 ；2.0.5 及更早版本支持 v10.x 版本，其他版本可能存在包兼容性的问题。
Node.js Connector >= v2.0.6 currently supports node versions >=v12.8.0 <= v12.9.1 || >=v10.20.0 <= v10.9.0; v10.x versions are supported in 2.0.5 and earlier, other versions may have package compatibility issues.
## 其他说明
## Other notes
Node.js 连接器的使用参见[视频教程](https://www.taosdata.com/blog/2020/11/11/1957.html)。
See [video tutorial](https://www.taosdata.com/blog/2020/11/11/1957.html) for the Node.js connector.
## 常见问题
## Frequently Asked Questions
1. 使用 REST 连接需要启动 taosadapter。
1. Using REST connections requires starting taosadapter.
```bash
sudo systemctl start taosadapter
```
2. Node.js 版本
2. Node.js version
连接器 >v2.0.6 目前兼容的 Node.js 版本为：>=v10.20.0 <= v10.9.0 || >=v12.8.0 <= v12.9.1
Connector >v2.0.6 Currently compatible Node.js versions are: >=v10.20.0 <= v10.9.0 || >=v12.8.0 <= v12.9.1
3. "Unable to establish connection"，"Unable to resolve FQDN"
3. "Unable to establish connection", "Unable to resolve FQDN"
一般都是因为配置 FQDN 不正确。 可以参考[如何彻底搞懂 TDengine 的 FQDN](https://www.taosdata.com/blog/2021/07/29/2741.html) 。
Usually, it is because the FQDN is not configured correctly. You can refer to [How to understand TDengine's FQDN thoroughly](https://www.taosdata.com/blog/2021/07/29/2741.html).
## 重要更新记录
## Important Updates
### 原生连接器
### Native connectors
| td2.0-connector 版本 | 说明 |
| td2.0-connector version | description |
| -------------------- | ---------------------------------------------------------------- |
| 2.0.12 | 修复 cursor.close() 报错的 bug。 |
| 2.0.11 | 支持绑定参数、json tag、schemaless 接口等功能。 |
| 2.0.10 | 支持连接管理，普通查询、连续查询、获取系统信息、订阅功能等功能。 |
| 2.0.12 | Fix bug with cursor.close() error. | 2.0.12 | Fix bug with cursor.close() error.
| 2.0.11 | Support for binding parameters, json tag, schemaless interface, etc. |
| 2.0.10 | Support connection management, general query, continuous query, get system information, subscribe function, etc. | ### REST Connector
### REST 连接器
### REST Connector
| td2.0-rest-connector 版本 | 说明 |
| td2.0-rest-connector version | Description |
| ------------------------- | ---------------------------------------------------------------- |
| 1.0.3 | 支持连接管理、普通查询、获取系统信息、错误信息、连续查询等功能。 |
| 1.0.3 | Support connection management, general query, get system information, error message, continuous query, etc. |# API Reference
## API 参考
## API Reference
[API 参考](https://docs.taosdata.com/api/td2.0-connector/)
[API Reference](https://docs.taosdata.com/api/td2.0-connector/)
docs-en/14-reference/03-connector/python.mdx
浏览文件 @ b082e26a
......@@ -2,7 +2,7 @@
sidebar_position: 3
sidebar_label: Python
title: TDengine Python Connector
description: "taospy 是 TDengine 的官方 Python 连接器。taospy 提供了丰富的 API， 使得 Python 应用可以很方便地使用 TDengine。tasopy 对 TDengine 的原生接口和 REST 接口都进行了封装， 分别对应 tasopy 的两个子模块：tasos 和 taosrest。除了对原生接口和 REST 接口的封装，taospy 还提供了符合 Python 数据访问规范(PEP 249)的编程接口。这使得 taospy 和很多第三方工具集成变得简单，比如 SQLAlchemy 和 pandas"
description: "taospy is the official Python connector for TDengine. taospy provides a rich API that makes it easy for Python applications to use TDengine. tasopy wraps both the native and REST interfaces of TDengine, corresponding to the two submodules of tasopy: taos and taosrest. In addition to wrapping the native and REST interfaces, taospy also provides a programming interface that conforms to the Python Data Access Specification (PEP 249), making it easy to integrate taospy with many third-party tools, such as SQLAlchemy and pandas."
---
import Tabs from "@theme/Tabs";
......
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或