ODBC连接器配置

• 前提条件
• “connection”配置节
  • “attributes”子配置节
  • “decoding”子配置节
• “pyodbc”配置节
• “converter”属性
• “polling”配置节
  • “iterator”子配置节
• “mapping”配置节
  • “device”子配置节
  • “attributes”和”timeseries”子配置节
• “serverSideRpc”配置节
• 下一步

本指南将帮助您熟悉ThingsBoard IoT Gateway的ODBC连接器配置。 请使用通用配置启用此连接器。 下面将说明连接器配置文件。

ODBC连接器配置文件示例。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
{
  "connection": {
    "str": "Driver={PostgreSQL};Server=localhost;Port=5432;Database=thingsboard;Uid=postgres;Pwd=postgres;",
    "attributes": {
      "autocommit": true,
      "timeout": 0
    },
    "encoding": "utf-8",
    "decoding": {
      "char": "utf-8",
      "wchar": "utf-8",
      "metadata": "utf-16le"
    },
    "reconnect": true,
    "reconnectPeriod": 60
  },
  "pyodbc": {
    "pooling": false
  },
  "polling": {
    "query": "SELECT bool_v, str_v, dbl_v, long_v, entity_id, ts FROM ts_kv WHERE ts > ? ORDER BY ts ASC LIMIT 10",
    "period": 5,
    "iterator": {
      "column": "ts",
      "query": "SELECT MIN(ts) - 1 FROM ts_kv",
      "save": false
    }
  },
  "mapping": {
    "device": {
      "type": "postgres",
      "name": "'ODBC ' + entity_id"
    },
    "sendDataOnlyOnChange": false,
    "attributes": "*",
    "timeseries": [
      "ts",
      {
        "name": "value",
        "value": "[i for i in [str_v, long_v, dbl_v,bool_v] if i is not None][0]"
      }
    ]
  },
  "serverSideRpc": {
    "enableUnknownRpc": true,
    "methods": [
      "procedureOne",
      {
        "name": "procedureTwo",
        "args": [ "One", 2, 3.0 ]
      }
    ]
  }
}

前提条件

要安装并使ODBC连接器正常工作，需要完成以下几个额外步骤：

1.在Windows上安装Visual C++ Redistributable包，或在Linux上安装ODBC包。 2.为ThingsBoard网关需要连接的数据库安装ODBC驱动程序。 3.在Windows上通过ODBC数据源管理器添加数据源，或在Unix系统上将驱动程序信息（名称、库路径等）添加到ODBC配置文件odbcinst.ini中。

“connection”配置节

此必填配置节提供如何连接或重新连接ODBC数据库的信息。

注意：有关编码/解码的更多信息，请参阅文档。

“attributes”子配置节

此可选子配置节提供多个选项来调整连接过程。

“decoding”子配置节

此可选子配置节提供如何解码从数据库读取的字符串数据和元数据的信息。

注意：有关编码/解码的更多信息，请参阅此文档。

“pyodbc”配置节

此可选配置节提供选项来调整ODBC连接器底层使用的pyodbc Python库。

1
2
3
4
"pyodbc": {
  "pooling": false,
  "native_uuid": true
},

“converter”属性

ODBC连接器内置了上行数据转换器。您可以在此可选属性中指定自定义转换器类。

1
"converter": "CustomOdbcUplinkConverter",

“polling”配置节

ODBC连接器的核心思想是定期查询ODBC数据库以检查是否有新数据出现。

此必填配置节提供查询数据库的频率、要选择的数据以及用于遍历结果集的数据库列的信息。

query选项的要求：

1.有效的SQL SELECT语句，需满足ThingsBoard网关所连接数据库的SQL方言要求。 2.在_SELECT_列表中包含attributes和/或timeseries列。 3.在_SELECT_列表中包含device列，用于确定数据所属的设备。 4.在_SELECT_列表中包含iterator列。

1. SQL _WHERE_子句中除其他条件外，还必须包含iterator条件。
2. SQL _ORDER BY_子句中除其他排序表达式外，还必须包含iterator排序表达式。
3. 建议使用SQL _LIMIT_子句来减少每次从数据库读取时的内存消耗。

示例：

每次轮询迭代中，连接器将按_ts_列（iterator）排序读取10条记录。

每条记录包含时间序列列（bool_v、str_v、dbl_v、long_v）、device列（entity_id）和iterator列（ts）。

每次轮询迭代后，连接器会记住第10条记录（最后一条记录）的ts列的值，并在下一次迭代的_WHERE_子句中使用它。

1
2
3
4
5
SELECT bool_v, str_v, dbl_v, long_v, entity_id, ts   (2-3)
FROM ts_kv
WHERE ts > ?                                         (4)
ORDER BY ts ASC                                      (5)
LIMIT 10                                             (6)

“iterator”子配置节

此必填子配置节提供用于遍历结果集的数据库列、迭代器初始值的获取方式以及是否在网关工作会话之间使用迭代器数据的信息。

重要提示

iterator功能的主要挑战在于明确判断是从上一次网关工作会话中恢复迭代器数据，还是使用连接器配置文件中的值。

每个iterator都有自己的文件，存储在config/odbc/文件夹中。每次轮询迭代后，连接器会将iterator数据（参见下面的persistent选项）保存到该文件中。

-连接器如何区分不同的迭代器文件？

-简短回答：基于iterator文件名来决定。

具体来说，连接器启动并连接到数据库后，会检查persistent标志（见下文）是否设置为true。如果是，连接器会计算iterator文件名并检查该文件是否存在于config/odbc/文件夹中。

如果文件存在，连接器会从中加载iterator数据。否则，iterator数据将从连接器的配置文件中加载。

iterator文件名是以下内容的哈希值：

• ODBC驱动程序名称 数据库服务器名称 *数据库名称 *迭代器列（参见下面的column*选项）

缺陷

可能出现这种情况：使用同一数据库时表列表已完全更改，但iterator列名未更改，仅仅因为不同的表使用了相同的列名。在这种情况下，连接器会加载错误的iterator数据。

结论

1.对于同一数据库，为每个迭代器使用唯一的名称。 2.仅在连接器的其他配置部分已调试完毕且属性和时间序列列表已最终确定后，才启用_iterator_持久化功能。

注意：value和query选项互斥。如果两个选项都设置了，将使用_value_。

“mapping”配置节

此必填配置节提供如何将从数据库接收的结果集映射到设备属性和时间序列值的信息。

“device”子配置节

此必填子配置节提供如何将结果集映射到唯一设备名称及其类型的信息。

注意：SQL SELECT子句中在query选项里列出的所有数据库列，均可在Python eval()上下文中通过列名访问。

例如，

1
2
3
"device": {
  "name": "'ODBC' + entity_id"
}

表示设备名称是两个字符串的拼接结果：ODBC和数据库列entity_id的值。

“attributes”和”timeseries”子配置节

这些可选子配置节提供哪些数据库列应被视为属性、哪些应被视为时间序列键，以及在将数据发送到ThingsBoard服务器之前应执行哪些预处理任务的信息。

连接器支持以下几种配置模式：

*数据库列列表

1
"timeseries": [ "str_v", "ts" ]

*配置列表

1
2
3
4
5
6
7
8
9
10
11
12
13
14
"timeseries": [
  {
    "name": "boolValue",
    "column": "bool_v"
  },
  {
    "nameExpression": "key_name",
    "value": "[i for i in [str_v, long_v, dbl_v,bool_v] if i is not None][0]"
  },
  {
    "name": "value",
    "value": "[i for i in [str_v, long_v, dbl_v,bool_v] if i is not None][0]"
  }
]

注意：SQL SELECT子句中在query选项里列出的所有数据库列，均可在Python eval()上下文中通过列名访问。

*组合模式

1
2
3
4
5
6
7
"timeseries": [
  "ts",
  {
    "name": "value",
    "value": "[i for i in [str_v, long_v, dbl_v,bool_v] if i is not None][0]"
  }
]

*通配模式

1
"timeseries": "*"

，表示将所有数据库列视为时间序列。

“serverSideRpc”配置节

连接器能够调用带参数或不带参数的SQL存储过程/函数。参数可从连接器的配置文件或从服务器接收的数据中获取。

连接器支持以下几种methods子配置节的配置模式：

*不带参数的存储过程/函数列表

1
"methods": [ "procedureOne", "procedureTwo" ]

*存储过程/函数配置列表

参数顺序很重要。它必须与SQL存储过程/函数中的参数顺序一致。

1
2
3
4
5
6
7
8
9
10
11
"methods": [
  {
    "name": "rpcProcOne",
    "args": [ "One", 2, 3.0 ],
    "query": "CALL procedureOne(?,?,?)"
  },
  {
    "name": "functionOne",
    "args": [ false ]
  }
]

存储过程/函数配置参数

*组合模式

1
2
3
4
5
6
7
"methods": [
  "procedureOne",
  {
    "name": "procedureTwo",
    "args": [ "One", 2, 3.0 ]
  }
]

重要提示

如果enableUnknownRpc设置为true，RPC参数必须包含所有必需的存储过程/函数配置参数。

如果overrideRpcConfig设置为true，RPC参数可以包含全部或部分存储过程/函数配置参数，以覆盖连接器配置文件中指定的参数。

参数顺序很重要。它必须与SQL存储过程/函数中的参数顺序一致。

1
2
3
4
5
6
7
8
9
{
  "device": "ODBC Device 1", 
  "data": {
    "method": "procedureOne", 
    "params": {
      "args": [ "OverridedValue", 123, 3.14 ]
    }
  }
}

下一步

探索与ThingsBoard主要功能相关的指南：

• 数据可视化 -如何可视化采集的数据。
• 设备属性 -如何使用设备属性。
• 遥测数据采集 -如何采集遥测数据。
• 使用RPC功能 -如何向设备发送命令/从设备接收命令。
• 规则引擎 -如何使用规则引擎分析设备数据。