diff --git a/docs/zh/14-reference/05-connector/20-go.mdx b/docs/zh/14-reference/05-connector/20-go.mdx index 97fc474e44..0c3dfa6681 100644 --- a/docs/zh/14-reference/05-connector/20-go.mdx +++ b/docs/zh/14-reference/05-connector/20-go.mdx @@ -396,4 +396,803 @@ TDengine Go 连接器支持订阅功能,应用 API 如下: ## API 参考 -全部 API 见 [driver-go 文档](https://pkg.go.dev/github.com/taosdata/driver-go/v3) +### database/sql 驱动 + +`driver-go` 实现了 Go 的 `database/sql/driver` 接口,可以直接使用 Go 的 `database/sql` 包。提供了三个驱动:`github.com/taosdata/driver-go/v3/taosSql` 、`github.com/taosdata/driver-go/v3/taosRestful` 和 `github.com/taosdata/driver-go/v3/taosWS` 分别对应 `原生连接`、`REST 连接` 和 `WebSocket 连接`。 + +#### DSN 规范 + +数据源名称具有通用格式,例如 [PEAR DB](http://pear.php.net/manual/en/package.database.db.intro-dsn.php),但没有类型前缀(方括号表示可选): + +``` text +[username[:password]@][protocol[(address)]]/[dbname][?param1=value1&...¶mN=valueN] +``` + +完整形式的 DSN: + +```text +username:password@protocol(address)/dbname?param=value +``` + +##### 原生连接 + +导入驱动: + +```go +import ( + "database/sql" + _ "github.com/taosdata/driver-go/v3/taosSql" +) +``` + +使用 `taosSql` 作为 `driverName` 并且使用一个正确的 DSN 作为 `dataSourceName` 如下: + +```go +var taosUri = "root:taosdata@tcp(localhost:6030)/" +taos, err := sql.Open("taosSql", taosUri) +``` + +支持的 DSN 参数: + +* `cfg` 指定 taos.cfg 目录 +* `cgoThread` 指定 cgo 同时执行的数量,默认为系统核数 +* `cgoAsyncHandlerPoolSize` 指定异步函数的 handle 大小,默认为 10000 + +##### Rest 连接 + +导入驱动: + +```go +import ( + "database/sql" + _ "github.com/taosdata/driver-go/v3/taosRestful" +) +``` + +使用 `taosRestful` 作为 `driverName` 并且使用一个正确的 DSN 作为 `dataSourceName` 如下: + +```go +var taosUri = "root:taosdata@http(localhost:6041)/" +taos, err := sql.Open("taosRestful", taosUri) +``` + +支持的 DSN 参数: + +* `disableCompression` 是否接受压缩数据,默认为 true 不接受压缩数据,如果传输数据使用 gzip 压缩设置为 false。 +* `readBufferSize` 读取数据的缓存区大小默认为 4K(4096),当查询结果数据量多时可以适当调大该值。 +* `token` 连接云服务时使用的 token。 +* `skipVerify` 是否跳过证书验证,默认为 false 不跳过证书验证,如果连接的是不安全的服务设置为 true。 + +##### WebSocket 连接 + +导入驱动: + +```go +import ( + "database/sql" + _ "github.com/taosdata/driver-go/v3/taosWS" +) +``` + +使用 `taosWS` 作为 `driverName` 并且使用一个正确的 DSN 作为 `dataSourceName` 如下: + +```go +var taosUri = "root:taosdata@ws(localhost:6041)/" +taos, err := sql.Open("taosWS", taosUri) +``` + +支持的 DSN 参数: + +* `enableCompression` 是否发送压缩数据,默认为 false 不发送压缩数据,如果传输数据使用压缩设置为 true。 +* `readTimeout` 读取数据的超时时间,默认为 5m。 +* `writeTimeout` 写入数据的超时时间,默认为 10s。 + +:::note + +- 与原生连接方式不同,REST 接口是无状态的。在使用 REST 连接时,需要在 SQL 中指定表、超级表的数据库名称。 +- 如果在 DSN 中指定了 dbname,那么,REST 连接会默认使用/rest/sql/dbname 作为 restful 请求的 url,在 SQL 中不需要指定 dbname。 + +::: + +### 连接功能 + +Go 驱动支持创建连接,返回支持 `sql/driver` 标准的 `Connector` 接口的对象,还提供了 `af` 包,扩充了一些无模式写入接口。 + +#### 标准接口 + +`database/sql` 包中创建连接的接口 + +- `func Open(driverName, dataSourceName string) (*DB, error)` + - **接口说明**:(`database/sql`)连接数据库 + - **参数说明**: + - `driverName`:驱动名称。 + - `dataSourceName`:连接参数 DSN。 + - **返回值**:连接对象,错误信息。 + +#### 扩展接口 + +`af` 包中创建连接的接口 + +- `func Open(host, user, pass, db string, port int) (*Connector, error)` + - **接口说明**:连接数据库。 + - **参数说明**: + - `host`:主机地址。 + - `user`:用户名。 + - `pass`:密码。 + - `db`:数据库名称。 + - `port`:端口号。 + - **返回值**:连接对象,错误信息。 + +#### 无模式写入 + +`af` 包中使用原生连接进行无模式写入的接口。 + +- `func (conn *Connector) InfluxDBInsertLines(lines []string, precision string) error` + - **接口说明**:无模式写入 influxDB 格式数据。 + - **参数说明**: + - `lines`:写入的数据。 + - `precision`:时间精度。 + - **返回值**:错误信息。 + +- `func (conn *Connector) OpenTSDBInsertJsonPayload(payload string) error` + - **接口说明**:无模式写入 OpenTSDB JSON 格式数据。 + - **参数说明**: + - `payload`:写入的数据。 + - **返回值**:错误信息。 + +- `func (conn *Connector) OpenTSDBInsertTelnetLines(lines []string) error` + - **接口说明**:无模式写入 OpenTSDB Telnet 格式数据。 + - **参数说明**: + - `lines`:写入的数据。 + - **返回值**:错误信息。 + +`ws/schemaless` 包中使用 WebSocket 无模式写入的接口 + +- `func (s *Schemaless) Insert(lines string, protocol int, precision string, ttl int, reqID int64) error` + - **接口说明**:无模式写入数据。 + - **参数说明**: + - `lines`:写入的数据。 + - `protocol`:写入的数据协议支持的协议 `InfluxDBLineProtocol = 1` `OpenTSDBTelnetLineProtocol = 2` `OpenTSDBJsonFormatProtocol = 3`。 + - `precision`:时间精度。 + - `ttl`:数据过期时间,0 表示不过期。 + - `reqID`:请求 ID。 + - **返回值**:错误信息。 + +### 执行 SQL + +Go 驱动提供了符合 `database/sql` 标准的接口,支持以下功能: + +1. **执行 SQL 语句**:执行静态 SQL 语句,并返回其生成的结果对象。 +2. **查询执行**:可以执行返回数据集的查询(`SELECT` 语句)。 +3. **更新执行**:可以执行影响行数的 SQL 语句,如 `INSERT`、`UPDATE`、`DELETE` 等。 +4. **获取结果**:可以获取查询执行后返回的结果集,并遍历查询返回的数据。 +5. **获取更新计数**:对于非查询 SQL 语句,可以获取执行后影响的行数。 +6. **关闭资源**:释放数据库资源。 + +#### 标准接口 + +- `func (db *DB) Close() error` + - **接口说明**:关闭连接。 + - **返回值**:错误信息。 + +- `func (db *DB) Exec(query string, args ...any) (Result, error)` + - **接口说明**:执行查询但不返回任何行。 + - **参数说明**: + - `query`:要执行的命令。 + - `args`:命令参数。 + - **返回值**:Result 对象(只有影响行数),错误信息。 + +- `func (db *DB) Query(query string, args ...any) (*Rows, error)` + - **接口说明**:执行查询并返回行的结果。 + - **参数说明**: + - `query`:要执行的命令。 + - `args`:命令参数。 + - **返回值**:Rows 对象,错误信息。 + +- `func (db *DB) QueryRow(query string, args ...any) *Row` + - **接口说明**:执行查询并返回一行结果。 + - **参数说明**: + - `query`:要执行的命令。 + - `args`:命令参数。 + - **返回值**:Row 对象。 + +#### 扩展接口 + +- `func (db *DB) ExecContext(ctx context.Context, query string, args ...any) (Result, error)` + - **接口说明**:执行查询但不返回任何行。 + - **参数说明**: + - `ctx`:上下文,使用 Value 传递请求 id 进行链路追踪,key 为 `taos_req_id` value 为 int64 类型值。 + - `query`:要执行的命令。 + - `args`:命令参数。 + - **返回值**:结果 Result 对象(只有影响行数),错误信息。 + +- `func (db *DB) QueryContext(ctx context.Context, query string, args ...any) (*Rows, error)` + - **接口说明**:执行查询并返回行结果。 + - **参数说明**: + - `ctx`:上下文,使用 Value 传递请求 id 进行链路追踪,key 为 `taos_req_id` value 为 int64 类型值。 + - `query`:要执行的命令。 + - `args`:命令参数。 + - **返回值**:结果集 Rows 对象,错误信息。 + +- `func (db *DB) QueryRowContext(ctx context.Context, query string, args ...any) *Row` + - **接口说明**:执行查询并返回一行结果,错误信息会在扫描 Row 时延迟返回。 + - **参数说明**: + - `ctx`:上下文,使用 Value 传递请求 id 进行链路追踪,key 为 `taos_req_id` value 为 int64 类型值。 + - `query`:要执行的命令。 + - `args`:命令参数。 + - **返回值**:单行结果 Row 对象。 + +### 结果获取 + +Go 驱动支持获取查询结果集,以及对应的结果集元数据,提供了用于读取结果集中元数据和数据的方法。 + +#### 结果集 + +通过 `Rows` 对象获取查询结果集,提供了以下方法: + +- `func (rs *Rows) Next() bool` + - **接口说明**:准备下一行数据。 + - **返回值**:是否有下一行数据。 + +- `func (rs *Rows) Columns() ([]string, error)` + - **接口说明**:返回列名。 + - **返回值**:列名,错误信息。 + +- `func (rs *Rows) Scan(dest ...any) error` + - **接口说明**:将当前行的列值复制到 dest 指向的值中。 + - **参数说明**: + - `dest`:目标值。 + - **返回值**:错误信息。 + +- `func (rs *Rows) Close() error` + - **接口说明**:关闭行。 + - **返回值**:错误信息。 + +- `func (r *Row) Scan(dest ...any) error` + - **接口说明**:将当前行的列值复制到 dest 指向的值中。 + - **参数说明**: + - `dest`:目标值。 + - **返回值**:错误信息。 + +通过 `Result` 对象获取更新结果集,提供了以下方法: + +- `func (dr driverResult) RowsAffected() (int64, error)` + - **接口说明**:返回受影响的行数。 + - **返回值**:受影响的行数,错误信息。 + +#### 结果集元数据 + +通过 `Rows` 对象获取查询结果集元数据,提供了以下方法: + +- `func (rs *Rows) ColumnTypes() ([]*ColumnType, error)` + - **接口说明**:返回列类型。 + - **返回值**:列类型,错误信息。 + +- `func (ci *ColumnType) Name() string` + - **接口说明**:返回列名。 + - **返回值**:列名。 + +- `func (ci *ColumnType) Length() (length int64, ok bool)` + - **接口说明**:返回列长度。 + - **返回值**:列长度,是否有长度。 + +- `func (ci *ColumnType) ScanType() reflect.Type` + - **接口说明**:返回列类型对应的 Go 类型。 + - **返回值**:列类型。 + +- `func (ci *ColumnType) DatabaseTypeName() string` + - **接口说明**:返回列类型数据库名称。 + - **返回值**:列类型名称。 + +### 参数绑定 + +Prepare 允许使用预编译的 SQL 语句,可以提高性能并提供参数化查询的能力,从而增加安全性。 + +#### 标准接口 + +使用 `sql/driver` 的 `Conn` 接口中的 `Prepare` 方法准备一个与此连接绑定的准备好的语句,返回 `Stmt` 对象,使用。 + +- `Prepare(query string) (Stmt, error)` + - **接口说明**:准备返回一个与此连接绑定的准备好的语句(statement)。 + - **参数说明**: + - `query`:要进行参数绑定的语句。 + - **返回值**:Stmt 对象,错误信息。 + +- `func (s *Stmt) Exec(args ...any) (Result, error)` + - **接口说明**:使用给定的参数执行准备好的语句并返回总结该语句效果的结果(只可以绑定列值,不支持绑定表名和 tag)。 + - **参数说明**: + - `args`:命令参数,Go 原始类型会自动转换数据库类型,类型不匹配可能会丢精度,建议使用与数据库相同的类型,时间类型使用 int64 或 `RFC3339Nano` 格式化后的字符串。 + - **返回值**:结果 Result 对象(只有影响行数),错误信息。 + +- `func (s *Stmt) Query(args ...any) (*Rows, error)` + - **接口说明**:使用给定的参数执行准备好的语句并返回行的结果。 + - **参数说明**: + - `args`:命令参数,Go 原始类型会自动转换数据库类型,类型不匹配可能会丢精度,建议使用与数据库相同的类型,时间类型使用 int64 或 `RFC3339Nano` 格式化后的字符串。 + - **返回值**:结果集 Rows 对象,错误信息。 + +- `func (s *Stmt) Close() error` + - **接口说明**:关闭语句。 + - **返回值**:错误信息。 + +#### 扩展接口 + +`af` 包中提供了使用原生连接进行参数绑定的更多接口 + +- `func (conn *Connector) Stmt() *Stmt` + - **接口说明**:返回一个与此连接绑定的 Stmt 对象。 + - **返回值**:Stmt 对象。 + +- `func (s *Stmt) Prepare(sql string) error` + - **接口说明**:准备一个 sql 。 + - **参数说明**: + - `sql`:要进行参数绑定的语句。 + - **返回值**:错误信息。 + +- `func (s *Stmt) NumParams() (int, error)` + - **接口说明**:返回参数数量。 + - **返回值**:参数数量,错误信息。 + +- `func (s *Stmt) SetTableNameWithTags(tableName string, tags *param.Param)` + - **接口说明**:设置表名和 tag。 + - **参数说明**: + - `tableName`:表名。 + - `tags`:tag。 + - **返回值**:错误信息。 + +- `func (s *Stmt) SetTableName(tableName string) error` + - **接口说明**:设置表名。 + - **参数说明**: + - `tableName`:表名。 + - **返回值**:错误信息。 + +- `func (s *Stmt) BindRow(row *param.Param) error` + - **接口说明**:绑定行。 + - **参数说明**: + - `row`:行数据。 + - **返回值**:错误信息。 + +- `func (s *Stmt) GetAffectedRows() int` + - **接口说明**:获取受影响的行数。 + - **返回值**:受影响的行数。 + +- `func (s *Stmt) AddBatch() error` + - **接口说明**:添加批处理。 + - **返回值**:错误信息。 + +- `func (s *Stmt) Execute() error` + - **接口说明**:执行批处理。 + - **返回值**:错误信息。 + +- `func (s *Stmt) UseResult() (driver.Rows, error)` + - **接口说明**:使用结果。 + - **返回值**:结果集 Rows 对象,错误信息。 + +- `func (s *Stmt) Close() error` + - **接口说明**:关闭语句。 + - **返回值**:错误信息。 + +`ws/stmt` 包提供了通过 WebSocket 进行参数绑定的接口 + +- `func (c *Connector) Init() (*Stmt, error)` + - **接口说明**:初始化。 + - **返回值**:Stmt 对象,错误信息。 + +- `func (s *Stmt) Prepare(sql string) error` + - **接口说明**:准备一个 sql 。 + - **参数说明**: + - `sql`:要进行参数绑定的语句。 + - **返回值**:错误信息。 + +- `func (s *Stmt) SetTableName(name string) error` + - **接口说明**:设置表名。 + - **参数说明**: + - `name`:表名。 + - **返回值**:错误信息。 + +- `func (s *Stmt) SetTags(tags *param.Param, bindType *param.ColumnType)` + - **接口说明**:设置 tag。 + - **参数说明**: + - `tags`:tag。 + - `bindType`:类型信息。 + - **返回值**:错误信息。 + +- `func (s *Stmt) BindParam(params []*param.Param, bindType *param.ColumnType) error` + - **接口说明**:绑定参数。 + - **参数说明**: + - `params`:参数。 + - `bindType`:类型信息。 + - **返回值**:错误信息。 + +- `func (s *Stmt) AddBatch() error` + - **接口说明**:添加批处理。 + - **返回值**:错误信息。 + +- `func (s *Stmt) Exec() error` + - **接口说明**:执行批处理。 + - **返回值**:错误信息。 + +- `func (s *Stmt) GetAffectedRows() int` + - **接口说明**:获取受影响的行数。 + - **返回值**:受影响的行数。 + +- `func (s *Stmt) UseResult() (*Rows, error)` + - **接口说明**:使用结果。 + - **返回值**:Rows 对象,错误信息。 + +- `func (s *Stmt) Close() error` + - **接口说明**:关闭语句。 + - **返回值**:错误信息。 + +Rows 行结果参考 `sql/driver` 包中的 `Rows` 接口,提供以下接口 + +- `func (rs *Rows) Columns() []string` + - **接口说明**:返回列名。 + - **返回值**:列名。 + +- `func (rs *Rows) ColumnTypeDatabaseTypeName(i int) string` + - **接口说明**:返回列类型数据库名称。 + - **参数说明**: + - `i`:列索引。 + - **返回值**:列类型名称。 + +- `func (rs *Rows) ColumnTypeLength(i int) (length int64, ok bool)` + - **接口说明**:返回列长度。 + - **参数说明**: + - `i`:列索引。 + - **返回值**:列长度,是否有长度。 + +- `func (rs *Rows) ColumnTypeScanType(i int) reflect.Type` + - **接口说明**:返回列类型对应的 Go 类型。 + - **参数说明**: + - `i`:列索引。 + - **返回值**:列类型。 + +- `func (rs *Rows) Next(dest []driver.Value) error` + - **接口说明**:准备下一行数据,并赋值给目标。 + - **参数说明**: + - `dest`:目标值。 + - **返回值**:错误信息。 + +- `func (rs *Rows) Close() error` + - **接口说明**:关闭行。 + - **返回值**:错误信息。 + + +`common/param` 包中提供了参数绑定数据结构 + +以下是按照偏移设置参数的接口: + +- `func NewParam(size int) *Param` + - **接口说明**:创建一个参数绑定数据结构。 + - **参数说明**: + - `size`:参数数量。 + - **返回值**:Param 对象。 + +- `func (p *Param) SetBool(offset int, value bool)` + - **接口说明**:设置布尔值。 + - **参数说明**: + - `offset`:偏移量(列或标签)。 + - `value`:布尔值。 + +- `func (p *Param) SetNull(offset int)` + - **接口说明**:设置空值。 + - **参数说明**: + - `offset`:偏移量(列或标签)。 + +- `func (p *Param) SetTinyint(offset int, value int)` + - **接口说明**:设置 Tinyint 值。 + - **参数说明**: + - `offset`:偏移量(列或标签)。 + - `value`:Tinyint 值。 + +- `func (p *Param) SetSmallint(offset int, value int)` + - **接口说明**:设置 Smallint 值。 + - **参数说明**: + - `offset`:偏移量(列或标签)。 + - `value`:Smallint 值。 + +- `func (p *Param) SetInt(offset int, value int)` + - **接口说明**:设置 Int 值。 + - **参数说明**: + - `offset`:偏移量(列或标签)。 + - `value`:Int 值。 + +- `func (p *Param) SetBigint(offset int, value int)` + - **接口说明**:设置 Bigint 值。 + - **参数说明**: + - `offset`:偏移量(列或标签)。 + - `value`:Bigint 值。 + +- `func (p *Param) SetUTinyint(offset int, value uint)` + - **接口说明**:设置 UTinyint 值。 + - **参数说明**: + - `offset`:偏移量(列或标签)。 + - `value`:UTinyint 值。 + +- `func (p *Param) SetUSmallint(offset int, value uint)` + - **接口说明**:设置 USmallint 值。 + - **参数说明**: + - `offset`:偏移量(列或标签)。 + - `value`:USmallint 值。 + +- `func (p *Param) SetUInt(offset int, value uint)` + - **接口说明**:设置 UInt 值。 + - **参数说明**: + - `offset`:偏移量(列或标签)。 + - `value`:UInt 值。 + +- `func (p *Param) SetUBigint(offset int, value uint)` + - **接口说明**:设置 UBigint 值。 + - **参数说明**: + - `offset`:偏移量(列或标签)。 + - `value`:UBigint 值。 + +- `func (p *Param) SetFloat(offset int, value float32)` + - **接口说明**:设置 Float 值。 + - **参数说明**: + - `offset`:偏移量(列或标签)。 + - `value`:Float 值。 + +- `func (p *Param) SetDouble(offset int, value float64)` + - **接口说明**:设置 Double 值。 + - **参数说明**: + - `offset`:偏移量(列或标签)。 + - `value`:Double 值。 + +- `func (p *Param) SetBinary(offset int, value []byte)` + - **接口说明**:设置 Binary 值。 + - **参数说明**: + - `offset`:偏移量(列或标签)。 + - `value`:Binary 值。 + +- `func (p *Param) SetVarBinary(offset int, value []byte)` + - **接口说明**:设置 VarBinary 值。 + - **参数说明**: + - `offset`:偏移量(列或标签)。 + - `value`:VarBinary 值。 + +- `func (p *Param) SetNchar(offset int, value string)` + - **接口说明**:设置 Nchar 值。 + - **参数说明**: + - `offset`:偏移量(列或标签)。 + - `value`:Nchar 值。 + +- `func (p *Param) SetTimestamp(offset int, value time.Time, precision int)` + - **接口说明**:设置 Timestamp 值。 + - **参数说明**: + - `offset`:偏移量(列或标签)。 + - `value`:Timestamp 值。 + - `precision`:时间精度。 + +- `func (p *Param) SetJson(offset int, value []byte)` + - **接口说明**:设置 Json 值。 + - **参数说明**: + - `offset`:偏移量(列或标签)。 + - `value`:Json 值。 + +- `func (p *Param) SetGeometry(offset int, value []byte)` + - **接口说明**:设置 Geometry 值。 + - **参数说明**: + - `offset`:偏移量(列或标签)。 + - `value`:Geometry 值。 + +以下是链式调用设置参数的接口: + +- `func (p *Param) AddBool(value bool) *Param` + - **接口说明**:添加布尔值。 + - **参数说明**: + - `value`:布尔值。 + - **返回值**:Param 对象。 + +其他类型与布尔值类似,具体接口如下: + +- AddNull +- AddTinyint +- AddSmallint +- AddInt +- AddBigint +- AddUTinyint +- AddUSmallint +- AddUInt +- AddUBigint +- AddFloat +- AddDouble +- AddBinary +- AddVarBinary +- AddNchar +- AddTimestamp +- AddJson +- AddGeometry + +以下是设置列类型信息的接口: + +- `func NewColumnType(size int) *ColumnType` + - **接口说明**:创建一个列类型信息数据结构。 + - **参数说明**: + - `size`:列数量。 + - **返回值**:ColumnType 对象。 + +- `func (c *ColumnType) AddBool() *ColumnType` + - **接口说明**:添加布尔类型。 + - **返回值**:ColumnType 对象。 + +其他类型与布尔类型类似,具体接口如下: + +- AddTinyint +- AddSmallint +- AddInt +- AddBigint +- AddUTinyint +- AddUSmallint +- AddUInt +- AddUBigint +- AddFloat +- AddDouble +- AddBinary +- AddVarBinary +- AddNchar +- AddTimestamp +- AddJson +- AddGeometry + + +### 数据订阅 + +Go 驱动支持数据订阅功能,提供了基于原生连接和 WebSocket 连接的数据订阅接口。原生实现在 `af/tmq` 包中,WebSocket 实现在 `ws/tmq` 包中。 + +#### 消费者 + +- `func NewConsumer(conf *tmq.ConfigMap) (*Consumer, error)` + - **接口说明**:创建一个消费者。 + - **参数说明**: + - `conf`:配置信息。 + - **返回值**:Consumer 对象,错误信息。 + +配置信息定义为: + +```go +type ConfigValue interface{} +type ConfigMap map[string]ConfigValue +``` +创建消费者支持属性列表: + +- `ws.url`:WebSocket 连接地址。 +- `ws.message.channelLen`:WebSocket 消息通道缓存长度,默认 0。 +- `ws.message.timeout`:WebSocket 消息超时时间,默认 5m。 +- `ws.message.writeWait`:WebSocket 写入消息超时时间,默认 10s。 +- `ws.message.enableCompression`:WebSocket 是否启用压缩,默认 false。 +- `ws.autoReconnect`:WebSocket 是否自动重连,默认 false。 +- `ws.reconnectIntervalMs`:WebSocket 重连间隔时间毫秒,默认 2000。 +- `ws.reconnectRetryCount`:WebSocket 重连重试次数,默认 3。 + +其他参数请参考:[Consumer 参数列表](../../develop/tmq/#数据订阅相关参数), 注意TDengine服务端自 3.2.0.0 版本开始消息订阅中的 auto.offset.reset 默认值发生变化。 + +- `func (c *Consumer) Subscribe(topic string, rebalanceCb RebalanceCb) error` + - **接口说明**:订阅主题。 + - **参数说明**: + - `topic`:主题。 + - `rebalanceCb`:平衡回调(未使用)。 + - **返回值**:错误信息。 + +- `func (c *Consumer) SubscribeTopics(topics []string, rebalanceCb RebalanceCb) error` + - **接口说明**:订阅主题列表。 + - **参数说明**: + - `topics`:主题列表。 + - `rebalanceCb`:平衡回调(未使用)。 + - **返回值**:错误信息。 + +- `func (c *Consumer) Unsubscribe() error` + - **接口说明**:取消订阅。 + - **返回值**:错误信息。 + +- `func (c *Consumer) Poll(timeoutMs int) tmq.Event` + - **接口说明**:轮询事件。 + - **参数说明**: + - `timeoutMs`:超时时间。 + - **返回值**:事件。 + +- `func (c *Consumer) Commit() ([]tmq.TopicPartition, error)` + - **接口说明**:提交偏移量。 + - **返回值**:TopicPartition 列表,错误信息。 + +- `func (c *Consumer) Assignment() (partitions []tmq.TopicPartition, err error)` + - **接口说明**:获取分配信息。 + - **返回值**:TopicPartition 列表,错误信息。 + +- `func (c *Consumer) Seek(partition tmq.TopicPartition, ignoredTimeoutMs int) error` + - **接口说明**:跳转到偏移量。 + - **参数说明**: + - `partition`:分区和偏移信息。 + - `ignoredTimeoutMs`:超时时间(未使用)。 + - **返回值**:错误信息。 + +- `func (c *Consumer) Committed(partitions []tmq.TopicPartition, timeoutMs int) (offsets []tmq.TopicPartition, err error)` + - **接口说明**:获取提交的偏移量。 + - **参数说明**: + - `partitions`:分区列表。 + - `timeoutMs`:超时时间。 + - **返回值**:TopicPartition 列表,错误信息。 + +- `func (c *Consumer) CommitOffsets(offsets []tmq.TopicPartition) ([]tmq.TopicPartition, error) ` + - **接口说明**:提交偏移量。 + - **参数说明**: + - `offsets`:偏移量列表。 + - **返回值**:TopicPartition 列表,错误信息。 + +- `func (c *Consumer) Position(partitions []tmq.TopicPartition) (offsets []tmq.TopicPartition, err error)` + - **接口说明**:获取当前偏移量。 + - **参数说明**: + - `partitions`:分区列表。 + - **返回值**:TopicPartition 列表,错误信息。 + +- `func (c *Consumer) Close() error` + - **接口说明**:关闭消费者。 + - **返回值**:错误信息。 + +#### 消费记录 + +当 `Poll` 返回 `tmq.Event` 事件时,可以通过判断 `tmq.Event` 的类型获取消费记录或错误信息。当类型为 `*tmq.DataMessage` 时,可以获取消费记录。 + +- `func (m *DataMessage) Topic() string` + - **接口说明**:获取主题。 + - **返回值**:主题。 + +- `func (m *DataMessage) DBName() string` + - **接口说明**:获取数据库名称。 + - **返回值**:数据库名称。 + +- `func (m *DataMessage) Offset() Offset` + - **接口说明**:获取偏移量。 + - **返回值**:偏移量。 + +- `func (m *DataMessage) Value() interface{}` + - **接口说明**:获取值,具体值为 `[]*tmq.data`。 + - **返回值**:消费到的值。 + +tmq.data 结构如下: + +```go +type Data struct { + TableName string + Data [][]driver.Value +} +``` + +- TableName 为表名 +- Data 为数据,每个元素为一行数据,每行数据为一个数组,数组元素为列值。 + +当 Poll 返回类型为 `tmq.Error` 时,可以使用 `func (e Error) Error() string` 获取错误信息。 + +#### 分区信息 + +当消费到数据类型为 `*tmq.DataMessage` 时,可以从 `TopicPartition` 属性中获取分区信息。 + +```go +type TopicPartition struct { + Topic *string + Partition int32 + Offset Offset + Metadata *string + Error error +} +``` + +- `Topic`:主题。 +- `Partition`:分区。 +- `Offset`:偏移量。 +- `Metadata`:元数据(未使用)。 +- `Error`:错误信息。 + +可以使用 `func (p TopicPartition) String() string` 获取分区信息。 + +#### 偏移量元数据 + +从 `TopicPartition` 中获取的偏移量信息,可以通过 `Offset` 属性获取偏移量元数据。当偏移量为 `-2147467247` 时表示未设置偏移量。 + +#### 反序列化 + +当消费到数据类型为 `*tmq.DataMessage` 时,可以使用 `func (m *DataMessage) Value() interface{}` 获取数据,数据类型为 `[]*tmq.data` 。 + +## 附录 + +[driver-go 文档](https://pkg.go.dev/github.com/taosdata/driver-go/v3) diff --git a/docs/zh/14-reference/05-connector/40-csharp.mdx b/docs/zh/14-reference/05-connector/40-csharp.mdx index a175e6bf05..ad316d581c 100644 --- a/docs/zh/14-reference/05-connector/40-csharp.mdx +++ b/docs/zh/14-reference/05-connector/40-csharp.mdx @@ -1207,3 +1207,741 @@ namespace WSADO ### 更多示例程序 [示例程序](https://github.com/taosdata/taos-connector-dotnet/tree/3.0/examples) + +## API 参考 + +### ADO.NET 驱动 + +`TDengine.Data.Client` 接口实现了 ADO.NET 驱动,支持连接 TDengine 数据库,进行数据操作。 + +#### 参数规范 + +ConnectionStringBuilder 使用 key-value 对方式设置连接参数,key 为参数名,value 为参数值,不同参数之间使用分号 `;` 分割。 + +例如: + +```csharp +"protocol=WebSocket;host=127.0.0.1;port=6041;useSSL=false" +``` + +##### 原生连接 + +例如:`"host=127.0.0.1;port=6030;username=root;password=taosdata;protocol=Native;db=test"` + +支持的参数如下: + +- `host`:TDengine 运行实例的地址。 +- `port`:TDengine 运行实例的端口。 +- `username`:连接的用户名。 +- `password`:连接的密码。 +- `protocol`:连接的协议,可选值为 Native 或 WebSocket,默认为 Native。 +- `db`:连接的数据库。 +- `timezone`:时区,默认为本地时区。 + +##### WebSocket 连接 + +例如:`"protocol=WebSocket;host=127.0.0.1;port=6041;useSSL=false;enableCompression=true;autoReconnect=true;reconnectIntervalMs=10;reconnectRetryCount=5"` + +支持的参数如下: + +- `host`:TDengine 运行实例的地址。 +- `port`:TDengine 运行实例的端口。 +- `username`:连接的用户名。 +- `password`:连接的密码。 +- `protocol`:连接的协议,可选值为 Native 或 WebSocket,默认为 Native。 +- `db`:连接的数据库。 +- `timezone`:时区,默认为本地时区。 +- `connTimeout`:连接超时时间,默认为 1 分钟。 +- `readTimeout`:读取超时时间,默认为 5 分钟。 +- `writeTimeout`:发送超时时间,默认为 10 秒。 +- `token`:连接 TDengine cloud 的 token。 +- `useSSL`:是否使用 SSL 连接,默认为 false。 +- `enableCompression`:是否启用 WebSocket 压缩,默认为 false。 +- `autoReconnect`:是否自动重连,默认为 false。 +- `reconnectRetryCount`:重连次数,默认为 3。 +- `reconnectIntervalMs`:重连间隔毫秒时间,默认为 2000。 + +#### 接口说明 + +`ConnectionStringBuilder` 类提供了连接配置字符串的解析功能。 + +- `public ConnectionStringBuilder(string connectionString)` + - **接口说明**:ConnectionStringBuilder 构造函数。 + - **参数说明**: + - `connectionString`:连接配置字符串。 + +### 连接功能 + +C# 驱动支持创建 ADO.NET 连接,返回支持 ADO.NET 标准的 `DbConnection` 接口的对象,还提供了 `ITDengineClient` 接口,扩充了一些无模式写入接口。 + +#### 标准接口 + +ADO.NET 连接支持的标准接口如下: + +- `public TDengineConnection(string connectionString)` + - **接口说明**:TDengineConnection 构造函数。 + - **参数说明**: + - `connectionString`:连接配置字符串。 + - **异常**:格式错误抛出 `ArgumentException` 异常。 + +- `public void ChangeDatabase(string databaseName)` + - **接口说明**:切换数据库。 + - **参数说明**: + - `databaseName`:数据库名。 + - **异常**:执行失败抛出 `TDengineError` 异常。 + +- `public void Close()` + - **接口说明**:关闭连接。 + +- `public void Open()` + - **接口说明**:打开连接。 + - **异常**:打开失败抛出 `TDengineError` 异常,WebSocket 连接可能存在网络异常须注意处理。 + +- `public string ServerVersion` + - **接口说明**:返回服务器版本。 + - **返回值**:服务器版本字符串。 + - **异常**:执行失败抛出 `TDengineError` 异常。 + +- `public string DataSource` + - **接口说明**:返回数据源。 + - **返回值**:创建连接 host 配置。 + +- `public string Database` + - **接口说明**:返回连接数据库。 + - **返回值**:创建连接 db 配置。 + +- `public TDengineCommand(TDengineConnection connection)` + - **接口说明**:TDengineCommand 构造函数。 + - **参数说明**: + - `connection`:TDengineConnection 对象。 + - **异常**:执行失败抛出 `TDengineError` 异常。 + +- `public void Prepare()` + - **接口说明**:检查连接和命令文本,并准备命令执行。 + - **异常**:未执行 open 或未设置 CommandText 抛出 `InvalidOperationException` 异常。 + +- `public string CommandText` + - **接口说明**:获取或设置命令文本。 + - **返回值**:命令文本。 + +- `public new virtual TDengineParameterCollection Parameters` + - **接口说明**:获取参数集合。 + - **返回值**:TDengineParameterCollection 对象。 + + +#### 无模式写入 + +- `public static ITDengineClient Open(ConnectionStringBuilder builder)` + - **接口说明**:打开连接。 + - **参数说明**: + - `builder`:连接配置。 + - **返回值**:ITDengineClient 接口。 + - **异常**:打开失败抛出 `TDengineError` 异常,WebSocket 连接可能存在网络异常须注意处理。 + +- `void SchemalessInsert(string[] lines, TDengineSchemalessProtocol protocol,TDengineSchemalessPrecision precision, int ttl, long reqId)` + - **接口说明**:无模式写入。 + - **参数说明**: + - `lines`:数据行数组。 + - `protocol`:数据协议,支持协议:`TSDB_SML_LINE_PROTOCOL = 1` `TSDB_SML_TELNET_PROTOCOL = 2` `TSDB_SML_JSON_PROTOCOL = 3`。 + - `precision`:时间精度,支持配置:`TSDB_SML_TIMESTAMP_NOT_CONFIGURED = 0` `TSDB_SML_TIMESTAMP_HOURS = 1` `TSDB_SML_TIMESTAMP_MINUTES = 2` `TSDB_SML_TIMESTAMP_SECONDS = 3` `TSDB_SML_TIMESTAMP_MILLI_SECONDS = 4` `TSDB_SML_TIMESTAMP_MICRO_SECONDS = 5` `TSDB_SML_TIMESTAMP_NANO_SECONDS = 6`。 + - `ttl`:数据过期时间,0表示不配置。 + - `reqId`:请求 ID。 + - **异常**:执行失败抛出 `TDengineError` 异常。 + +### 执行 SQL + +C# 驱动提供了符合 ADO.NET 标准的 `DbCommand` 接口,支持以下功能: + +1. **执行 SQL 语句**:执行静态 SQL 语句,并返回其生成的结果对象。 +2. **查询执行**:可以执行返回数据集的查询(`SELECT` 语句)。 +3. **更新执行**:可以执行影响行数的 SQL 语句,如 `INSERT`、`UPDATE`、`DELETE` 等。 +4. **获取结果**:可以获取查询执行后返回的结果集(`ResultSet` 对象),并遍历查询返回的数据。 +5. **获取更新计数**:对于非查询 SQL 语句,可以获取执行后影响的行数。 +6. **关闭资源**:提供了关闭的方法,以释放数据库资源。 + +另外 C# 驱动还提供了用于请求链路跟踪的扩展接口。 + +#### 标准接口 + +- `public int ExecuteNonQuery()` + - **接口说明**:执行 SQL 语句,返回受影响的行数。 + - **返回值**:受影响的行数。 + - **异常**:执行失败抛出 `TDengineError` 异常。 + +- `public object ExecuteScalar()` + - **接口说明**:执行查询,并返回查询结果的第一行第一列。 + - **返回值**:查询结果的第一行第一列。 + - **异常**:执行失败抛出 `TDengineError` 异常。 + +- `public DbDataReader ExecuteReader()` + - **接口说明**:执行查询,并返回查询结果的数据读取器。 + - **返回值**:查询结果的数据读取器。 + - **异常**:执行失败抛出 `TDengineError` 异常。 + +- `public void Dispose();` + - **接口说明**:释放资源。 + +#### 扩展接口 + +扩展接口主要用于请求链路跟踪。 + +- `IRows Query(string query, long reqId)` + - **接口说明**:执行查询,返回查询结果。 + - **参数说明**: + - `query`:查询语句。 + - `reqId`:请求 ID。 + - **返回值**:查询结果。 + - **异常**:执行失败抛出 `TDengineError` 异常。 + +- `long Exec(string query, long reqId)` + - **接口说明**:执行 SQL 语句。 + - **参数说明**: + - `query`:SQL 语句。 + - `reqId`:请求 ID。 + - **返回值**:受影响的行数。 + - **异常**:执行失败抛出 `TDengineError` 异常。 + + +### 结果获取 + +C# 驱动提供了符合 ADO.NET 标准的 `DbDataReader` 接口,提供了用于读取结果集中元数据和数据的方法。 + +#### 结果集 + +`DbDataReader` 接口提供了以下方法获取结果集: + +- `public bool GetBoolean(int ordinal)` + - **接口说明**:获取指定列的布尔值。 + - **参数说明**: + - `ordinal`:列索引。 + - **返回值**:布尔值。 + - **异常**:类型不对应抛出 `InvalidCastException` 异常。 + +- `public byte GetByte(int ordinal)` + - **接口说明**:获取指定列的字节值。 + - **参数说明**: + - `ordinal`:列索引。 + - **返回值**:字节值。 + - **异常**:类型不对应抛出 `InvalidCastException` 异常。 + +- `public long GetBytes(int ordinal, long dataOffset, byte[] buffer, int bufferOffset, int length)` + - **接口说明**:获取指定列的字节值。 + - **参数说明**: + - `ordinal`:列索引。 + - `dataOffset`:数据偏移量。 + - `buffer`:缓冲区。 + - `bufferOffset`:缓冲区偏移量。 + - `length`:长度。 + - **返回值**:字节值。 + - **异常**:类型不对应抛出 `InvalidCastException` 异常。 + +- `public char GetChar(int ordinal)` + - **接口说明**:获取指定列的字符值。 + - **参数说明**: + - `ordinal`:列索引。 + - **返回值**:字符值。 + - **异常**:类型不对应抛出 `InvalidCastException` 异常。 + +- `public long GetChars(int ordinal, long dataOffset, char[] buffer, int bufferOffset, int length)` + - **接口说明**:获取指定列的字符值。 + - **参数说明**: + - `ordinal`:列索引。 + - `dataOffset`:数据偏移量。 + - `buffer`:缓冲区。 + - `bufferOffset`:缓冲区偏移量。 + - `length`:长度。 + - **返回值**:字符值。 + - **异常**:类型不对应抛出 `InvalidCastException` 异常。 + +- `public DateTime GetDateTime(int ordinal)` + - **接口说明**:获取指定列的日期时间值。 + - **参数说明**: + - `ordinal`:列索引。 + - **返回值**:日期时间值。 + - **异常**:类型不对应抛出 `InvalidCastException` 异常。 + +- `public double GetDouble(int ordinal)` + - **接口说明**:获取指定列的双精度浮点数值。 + - **参数说明**: + - `ordinal`:列索引。 + - **返回值**:双精度浮点数值。 + - **异常**:类型不对应抛出 `InvalidCastException` 异常。 + +- `public float GetFloat(int ordinal)` + - **接口说明**:获取指定列的单精度浮点数值。 + - **参数说明**: + - `ordinal`:列索引。 + - **返回值**:单精度浮点数值。 + - **异常**:类型不对应抛出 `InvalidCastException` 异常。 + +- `public short GetInt16(int ordinal)` + - **接口说明**:获取指定列的 16 位整数值。 + - **参数说明**: + - `ordinal`:列索引。 + - **返回值**:16 位整数值。 + - **异常**:类型不对应抛出 `InvalidCastException` 异常。 + +- `public int GetInt32(int ordinal)` + - **接口说明**:获取指定列的 32 位整数值。 + - **参数说明**: + - `ordinal`:列索引。 + - **返回值**:32 位整数值。 + - **异常**:类型不对应抛出 `InvalidCastException` 异常。 + +- `public long GetInt64(int ordinal)` + - **接口说明**:获取指定列的 64 位整数值。 + - **参数说明**: + - `ordinal`:列索引。 + - **返回值**:64 位整数值。 + - **异常**:类型不对应抛出 `InvalidCastException` 异常。 + +- `public string GetString(int ordinal)` + - **接口说明**:获取指定列的字符串值。 + - **参数说明**: + - `ordinal`:列索引。 + - **返回值**:字符串值。 + - **异常**:类型不对应抛出 `InvalidCastException` 异常。 + +- `public object GetValue(int ordinal)` + - **接口说明**:获取指定列的值。 + - **参数说明**: + - `ordinal`:列索引。 + - **返回值**: 结果对象。 + + +- `public int GetValues(object[] values)` + - **接口说明**:获取所有列的值。 + - **参数说明**: + - `values`:值数组。 + - **返回值**:值数量。 + +- `public bool IsDBNull(int ordinal)` + - **接口说明**:判断指定列是否为 NULL。 + - **参数说明**: + - `ordinal`:列索引。 + - **返回值**:是否为 NULL。 + +- `public int RecordsAffected` + - **接口说明**:获取受影响的行数。 + - **返回值**:受影响的行数。 + +- `public bool HasRows` + - **接口说明**:结果是否有行数据。 + - **返回值**:结果是否有行数据。 + +- `public bool Read()` + - **接口说明**:读取下一行。 + - **返回值**:是否读取成功。 + +- `public IEnumerator GetEnumerator()` + - **接口说明**:获取枚举器。 + - **返回值**:枚举器。 + +- `public void Close()` + - **接口说明**:关闭结果集。 + +#### 结果集元数据 + +`DbDataReader` 接口提供了以下方法获取结果集元数据: + +- `public DataTable GetSchemaTable()` + - **接口说明**:获取结果集元数据。 + - **返回值**:结果集元数据。 + +- `public string GetDataTypeName(int ordinal)` + - **接口说明**:获取指定列的数据类型名称。 + - **参数说明**: + - `ordinal`:列索引。 + - **返回值**:数据类型名称。 + +- ` public Type GetFieldType(int ordinal)` + - **接口说明**:获取指定列的数据类型。 + - **参数说明**: + - `ordinal`:列索引。 + - **返回值**:数据类型。 + +- `public string GetName(int ordinal)` + - **接口说明**:获取指定列的名称。 + - **参数说明**: + - `ordinal`:列索引。 + - **返回值**:列名称。 + +- ` public int GetFieldSize(int ordinal)` + - **接口说明**:获取指定列的大小。 + - **参数说明**: + - `ordinal`:列索引。 + - **返回值**:列大小。 + +- `public int GetOrdinal(string name)` + - **接口说明**:获取指定列的索引。 + - **参数说明**: + - `name`:列名称。 + - **返回值**:列索引。 + +- `public int FieldCount` + - **接口说明**:获取列数。 + - **返回值**:列数。 + +### 参数绑定 + +`TDengineCommand` 类支持参数绑定。 + +#### 标准接口 + +`TDengineCommand` 类继承了 `DbCommand` 接口,支持以下功能: + +- `public string CommandText` + - **接口说明**:获取或设置命令文本,支持参数绑定。 + - **返回值**:命令文本。 + +- `public new virtual TDengineParameterCollection Parameters` + - **接口说明**:获取参数集合。 + - **返回值**:`TDengineParameterCollection` 对象。 + +#### 参数元数据 + +`TDengineParameterCollection` 继承了 `DbParameterCollection` 接口,支持以下功能: + +- `public int Add(object value)` + - **接口说明**:添加参数。 + - **参数说明**: + - `value`:参数值。 + - **返回值**:参数索引。 + +- `public void Clear()` + - **接口说明**:清空参数。 + +- `public bool Contains(object value)` + - **接口说明**:是否包含参数。 + - **参数说明**: + - `value`:参数值。 + - **返回值**:是否包含参数。 + +- `public int IndexOf(object value)` + - **接口说明**:获取参数索引。 + - **参数说明**: + - `value`:参数值。 + - **返回值**:参数索引。 + +- `public void Insert(int index, object value)` + - **接口说明**:插入参数。 + - **参数说明**: + - `index`:索引。 + - `value`:参数值。 + +- `public void Remove(object value)` + - **接口说明**:移除参数。 + - **参数说明**: + - `value`:参数值。 + +- `public void RemoveAt(int index)` + - **接口说明**:移除参数。 + - **参数说明**: + - `index`:索引。 + +- `public void RemoveAt(string parameterName)` + - **接口说明**:移除参数。 + - **参数说明**: + - `parameterName`:参数名。 + +- `public int Count` + - **接口说明**:获取参数数量。 + - **返回值**:参数数量。 + +- `public int IndexOf(string parameterName)` + - **接口说明**:获取参数索引。 + - **参数说明**: + - `parameterName`:参数名。 + - **返回值**:参数索引。 + +- `public bool Contains(string value)` + - **接口说明**:是否包含参数。 + - **参数说明**: + - `value`:参数名。 + - **返回值**:是否包含参数。 + +- `public void CopyTo(Array array, int index)` + - **接口说明**:复制参数。 + - **参数说明**: + - `array`:目标数组。 + - `index`:索引。 + +- `public IEnumerator GetEnumerator()` + - **接口说明**:获取枚举器。 + - **返回值**:枚举器。 + +- `public void AddRange(Array values)` + - **接口说明**:添加参数。 + - **参数说明**: + - `values`:参数数组。 + +`TDengineParameter` 继承了 `DbParameter` 接口,支持以下功能: + +- `public TDengineParameter(string name, object value)` + - **接口说明**:TDengineParameter 构造函数。 + - **参数说明**: + - `name`:参数名,需要以 @ 开头,如 @0、@1、@2 等。 + - `value`:参数值,需要 C# 列类型与 TDengine 列类型一一对应。 + +- `public string ParameterName` + - **接口说明**:获取或设置参数名。 + - **返回值**:参数名。 + +- `public object Value` + - **接口说明**:获取或设置参数值。 + - **返回值**:参数值。 + +#### 扩展接口 + +`ITDengineClient` 接口提供了扩展的参数绑定接口。 + +- `IStmt StmtInit(long reqId)` + - **接口说明**:初始化 statement 对象。 + - **参数说明**: + - `reqId`:请求 ID。 + - **返回值**:实现 IStmt 接口的对象。 + - **异常**:执行失败抛出 `TDengineError` 异常。 + +`IStmt` 接口提供了扩展的参数绑定接口。 + +- `void Prepare(string query)` + - **接口说明**:准备 statement。 + - **参数说明**: + - `query`:查询语句。 + - **异常**:执行失败抛出 `TDengineError` 异常。 + +- `bool IsInsert()` + - **接口说明**:判断是否为插入语句。 + - **返回值**:是否为插入语句。 + - **异常**:执行失败抛出 `TDengineError` 异常。 + +- `void SetTableName(string tableName)` + - **接口说明**:设置表名。 + - **参数说明**: + - `tableName`:表名。 + - **异常**:执行失败抛出 `TDengineError` 异常。 + +- `void SetTags(object[] tags)` + - **接口说明**:设置标签。 + - **参数说明**: + - `tags`:标签数组。 + - **异常**:执行失败抛出 `TDengineError` 异常。 + +- `TaosFieldE[] GetTagFields()` + - **接口说明**:获取标签属性。 + - **返回值**:标签属性数组。 + - **异常**:执行失败抛出 `TDengineError` 异常。 + +- `TaosFieldE[] GetColFields()` + - **接口说明**:获取列属性。 + - **返回值**:列属性数组。 + - **异常**:执行失败抛出 `TDengineError` 异常。 + +- `void BindRow(object[] row)` + - **接口说明**:绑定行。 + - **参数说明**: + - `row`:行数据数组。 + - **异常**:执行失败抛出 `TDengineError` 异常。 + +- `void BindColumn( TaosFieldE[] fields,params Array[] arrays)` + - **接口说明**:绑定全部列。 + - **参数说明**: + - `fields`:字段属性数组。 + - `arrays`:多列数据数组。 + - **异常**:执行失败抛出 `TDengineError` 异常。 + +- `void AddBatch()` + - **接口说明**:添加批处理。 + - **异常**:执行失败抛出 `TDengineError` 异常。 + +- `void Exec()` + - **接口说明**:执行参数绑定。 + - **异常**:执行失败抛出 `TDengineError` 异常。 + +- `long Affected()` + - **接口说明**:获取受影响的行数。 + - **返回值**:受影响的行数。 + - **异常**:执行失败抛出 `TDengineError` 异常。 + +- `IRows Result()` + - **接口说明**:获取结果。 + - **返回值**:结果对象。 + - **异常**:执行失败抛出 `TDengineError` 异常。 + +### 数据订阅 + +`ConsumerBuilder` 类提供了消费者构建相关接口,`ConsumeResult` 类提供了消费结果相关接口,`TopicPartitionOffset` 类提供了分区偏移量相关接口。`ReferenceDeserializer` 和 `DictionaryDeserializer` 提供了反序列化的支持。 + +#### 消费者 + +- `public ConsumerBuilder(IEnumerable> config)` + - **接口说明**:ConsumerBuilder 构造函数。 + - **参数说明**: + - `config`:消费配置。 + +创建消费者支持属性列表: + +- `useSSL`:是否使用 SSL 连接,默认为 false +- `token`:连接 TDengine cloud 的 token +- `ws.message.enableCompression`:是否启用 WebSocket 压缩,默认为 false +- `ws.autoReconnect`:是否自动重连,默认为 false +- `ws.reconnect.retry.count`:重连次数,默认为 3 +- `ws.reconnect.interval.ms`:重连间隔毫秒时间,默认为 2000 + +其他参数请参考:[Consumer 参数列表](../../develop/tmq/#数据订阅相关参数), 注意TDengine服务端自 3.2.0.0 版本开始消息订阅中的 auto.offset.reset 默认值发生变化。 + +- `public IConsumer Build()` + - **接口说明**:构建消费者。 + - **返回值**:消费者对象。 + +`IConsumer` 接口提供了消费者相关 API: + +- `ConsumeResult Consume(int millisecondsTimeout)` + - **接口说明**:消费消息。 + - **参数说明**: + - `millisecondsTimeout`:毫秒超时时间。 + - **返回值**:消费结果。 + - **异常**:执行失败抛出 `TDengineError` 异常。 + +- `List Assignment { get; }` + - **接口说明**:获取分配信息。 + - **返回值**:分配信息。 + - **异常**:执行失败抛出 `TDengineError` 异常。 + +- `List Subscription()` + - **接口说明**:获取订阅的主题。 + - **返回值**:主题列表。 + - **异常**:执行失败抛出 `TDengineError` 异常。 + +- `void Subscribe(IEnumerable topic)` + - **接口说明**:订阅主题列表。 + - **参数说明**: + - `topic`:主题列表。 + - **异常**:执行失败抛出 `TDengineError` 异常。 + +- `void Subscribe(string topic)` + - **接口说明**:订阅单个主题。 + - **参数说明**: + - `topic`:主题。 + - **异常**:执行失败抛出 `TDengineError` 异常。 + +- `void Unsubscribe()` + - **接口说明**:取消订阅。 + - **异常**:执行失败抛出 `TDengineError` 异常。 + +- `void Commit(ConsumeResult consumerResult)` + - **接口说明**:提交消费结果。 + - **参数说明**: + - `consumerResult`:消费结果。 + - **异常**:执行失败抛出 `TDengineError` 异常。 + +- `List Commit()` + - **接口说明**:提交全部消费结果。 + - **返回值**:分区偏移量。 + - **异常**:执行失败抛出 `TDengineError` 异常。 + +- `void Commit(IEnumerable offsets)` + - **接口说明**:提交消费结果。 + - **参数说明**: + - `offsets`:分区偏移量。 + - **异常**:执行失败抛出 `TDengineError` 异常。 + +- `void Seek(TopicPartitionOffset tpo)` + - **接口说明**:跳转到分区偏移量。 + - **参数说明**: + - `tpo`:分区偏移量。 + - **异常**:执行失败抛出 `TDengineError` 异常。 + +- `List Committed(TimeSpan timeout)` + - **接口说明**:获取分区偏移量。 + - **参数说明**: + - `timeout`:超时时间(未使用)。 + - **返回值**:分区偏移量。 + - **异常**:执行失败抛出 `TDengineError` 异常。 + +- `List Committed(IEnumerable partitions, TimeSpan timeout)` + - **接口说明**:获取指定分区偏移量。 + - **参数说明**: + - `partitions`:分区列表。 + - `timeout`:超时时间(未使用)。 + - **返回值**:分区偏移量。 + - **异常**:执行失败抛出 `TDengineError` 异常。 + +- `Offset Position(TopicPartition partition)` + - **接口说明**:获取消费位置。 + - **参数说明**: + - `partition`:分区。 + - **返回值**:偏移量。 + - **异常**:执行失败抛出 `TDengineError` 异常。 + +- `void Close()` + - **接口说明**:关闭消费者。 + +#### 消费记录 + +`ConsumeResult` 类提供了消费结果相关接口: + +- `public List> Message` + - **接口说明**:获取消息列表。 + - **返回值**:消息列表。 + +`TmqMessage` 类提供了消息具体内容: + +```csharp + public class TmqMessage + { + public string TableName { get; set; } + public TValue Value { get; set; } + } +``` + +- `TableName`:表名 +- `Value`:消息内容 + +#### 分区信息 + +从 `ConsumeResult` 获取 `TopicPartitionOffset`: + +```csharp +public TopicPartitionOffset TopicPartitionOffset +``` + +`TopicPartitionOffset` 类提供了获取分区信息的接口: + +- `public string Topic { get; }` + - **接口说明**:获取主题。 + - **返回值**:主题。 + +- `public Partition Partition { get; }` + - **接口说明**:获取分区。 + - **返回值**:分区。 + +- `public Offset Offset { get; }` + - **接口说明**:获取偏移量。 + - **返回值**:偏移量。 + +- `public TopicPartition TopicPartition` + - **接口说明**:获取主题分区。 + - **返回值**:主题分区。 + +- `public string ToString()` + - **接口说明**:转换为字符串。 + - **返回值**:字符串信息。 + +#### 偏移量元数据 + +`Offset` 类提供了偏移量相关接口: + +- `public long Value` + - **接口说明**:获取偏移量值。 + - **返回值**:偏移量值。 + +#### 反序列化 + +C# 驱动提供了两个反序列化类:`ReferenceDeserializer` 和 `DictionaryDeserializer`。它们都实现了 `IDeserializer` 接口。 + +ReferenceDeserializer 用来将消费到的一条记录反序列化为一个对象,需要保证对象类的属性名与消费到的数据的列名能够对应,且类型能够匹配。 + +DictionaryDeserializer 则会将消费到的一行数据反序列化为一个 `Dictionary` 对象,其 key 为列名,值为对象。 + +ReferenceDeserializer 和 DictionaryDeserializer 的接口不会被用户直接调用,请参考使用样例。 \ No newline at end of file