跳到主要内容
版本：v3

ODBC

向本地 ODBC 驱动程序或可以在服务器同一机器上管理 ODBC 查询的远程 OIBus Agent 发送 SQL 查询。

OIBus agent 可以根据其文档中的说明单独安装。

当需要从 IP21 ODBC 接口或其他 ODBC 兼容应用程序检索数据时，此连接器非常有价值。

特定设置​

  • 使用远程代理：如果设置为 No，确保在部署 OIBus 的机器上安装了 ODBC 驱动程序。或者，您可以选择在配备必要驱动程序的远程机器上安装 OIBus agent。
  • 远程代理 URL：指定远程 OIBus agent 的 URL，例如，http://ip-address-or-host:2224。
  • 重试间隔：在重新尝试连接前的等待时间。
  • 请求超时：确定每个查询的超时持续时间。
  • 连接超时：建立连接的超时设置。
  • 连接字符串：ODBC 连接字符串。
  • 密码：认证密码，在 OIBus 配置中安全存储。如果直接包含在连接字符串中，密码将以明文存储。当使用密码时，OIBus 会在连接字符串的末尾附加 PWD=<password>。

请确保 ODBC 连接字符串符合指定驱动程序的格式，并且连接字符串中指定的驱动程序正确安装。

ODBC 连接字符串示例

Driver={驱动程序名称};SERVER=localhost,10014;TrustServerCertificate=yes;Database=test;UID=oibus;PWD=<secret>

驱动程序是驱动程序的名称（Windows）或驱动程序文件的路径（类 Unix 系统）。 端口是可选的，可以用 PORT=10014 替换（确保将逗号 , 替换为分号 ;）。

驱动程序安装​

在 Windows 上，您可以方便地访问 ODBC 驱动程序管理工具，在那里您可以在连接字符串中指定驱动程序的名称，例如 MySQL ODBC 3.51 驱动程序 或 SQL Server。

在类 UNIX 系统上，您应该先在您的机器上安装驱动程序，然后在连接字符串中指定驱动程序的路径，例如 /opt/lib/libmsodbcsql.18.dylib。

MacOS 上的 ODBC 潜水器

安装 unixodbc：brew install unixodbc. 检查安装是否成功，并列出 ODBC 配置文件：odbcinst -j 检查已安装的驱动程序：cat /opt/homebrew/etc/odbcinst.ini

与 IP21 使用 OIBus​

ODBC 连接通常会遇到延迟问题，特别是在大型历史查询期间，例如涉及 IP21 的查询。这可能会对网络和服务器造成重大负载。

为了减轻这些挑战，我们建议将 OIBus Agent 作为服务安装在与 IP21 相同的机器上。OIBus 然后可以使用 HTTP 协议将查询传输给其代理，代理可以直接使用 ODBC 与 IP21 通信，消除网络延迟。

当然，必须确保在 代理机器上 安装了适合的 ODBC 驱动程序，并在连接字符串中正确指定。

IP21 ODBC 驱动程序

要通过 ODBC 建立与 IP21 的连接，您需要在您的机器上安装 AspenTech SQLplus 驱动程序。 请确保此驱动程序正确安装。

ODBC 访问

认证可以通过连接字符串或本地处理。在选择本地认证时，重要的是确保 OIBus agent 以适当的权限运行。您可能需要以不同用户身份运行服务，这可以通过服务管理窗口配置。

以下连接字符串适用于基本的 IP21 安装：Driver={AspenTech SQLplus};HOST=<host>;PORT=10014"

项目设置​

在 South 连接器中，每个项目都可以根据选择的扫描模式进行配置以被查询。同一个 South 连接器内可以配置对同一数据库的多个查询。OIBus 将依次执行这些查询， 准备输出文件，然后将其发送到 North 连接器。

查询​

South 连接器中的查询字段接受 SQL 语法，并且可以利用几个内部变量。这些变量用于多种目的，包括在连接失败时增强数据流的韧性以及将大时间间隔分解为更小的块，这有助于减轻服务器和网络的负载。更多信息，请参考大查询部分。

查询变量​

在 OIBus 中，你可以使用以下内部变量，系统将解释这些变量：

  • @StartTime：最初，@StartTime 变量设置为查询第一次执行的日期。当从数据库检索到结果时，@StartTime 值更新为这些结果中用作参考的字段的最新时间戳（参考日期时间字段部分）。
  • @EndTime：@EndTime 变量设置为当前时间（now()）或者如果查询被分割，则为子间隔的结束时间。
包含 @StartTime 和 @EndTime 的 SQL 查询
SELECT data_name AS dataName, value, timestamp FROM table WHERE timestamp > @StartTime AND timestamp < @EndTime

日期时间字段​

在 South 连接器中，你可以指定一个由 datetime 类型字段组成的数组。每行指示 OIBus 将如何解析此字段以将其转换为内部 UTC 日期。这里是配置日期时间字段的详细信息：

  • 字段名称：查询的 SELECT 部分中的字段名称。
  • 参考字段：使用此字段作为下一个 @StartTime 值的参考（参考查询变量）。
  • 类型：结果中的数据类型。
  • 时区（对于字符串、Date、DateTime、DateTime2、SmallDateTime 类型）：数据库中存储的日期时间的时区。
  • 格式（仅限字符串）：数据库中存储的日期时间的字符串格式。
  • 区域设置（仅限字符串）：当格式包含特定于区域的字符串时使用的区域设置（如月份的 MMM 格式）。

OIBus 内部使用这些日期的 ISO UTC 格式，并且可以在序列化部分中设置输出日期时间格式。所有日期时间字段都使用相同的序列化设置进行转换。

SQL 查询中的转换

如果使用字符串类型的 timestamp 字段作为参考，格式为 yyyy-MM-dd HH:mm:ss，则 @StartTime 和 @EndTime 将被注入查询中为 yyyy-MM-dd HH:mm:ss 格式的字符串。

如果 timestamp 字段以字符串格式被用作参考，格式为 yyyy-MM-dd HH:mm:ss，则 @StartTime 和 @EndTime 将被注入查询中为 yyyy-MM-dd HH:mm:ss 格式的字符串。

在后续查询中，从数据库检索的 datetime 字段（转换为字符串 timestamp）是一个 DateTime 对象。OIBus 将从查询中解释 timestamp（字符串）字段作为参考字段。然而，以相同格式注入 @StartTime 和 @EndTime 作为字符串变量可能会由于注入的 @StartTime 和 @EndTime 变量（字符串类型）与数据库中的日期时间字段（格式化为 DateTime）之间的不一致而导致意外行为。

包含 @StartTime 和 @EndTime 以及转换的错误 SQL 查询
SELECT data_name AS dataName, value, convert(datetime, DATETIME) AS timestamp FROM table
WHERE datetime > @StartTime AND datetime < @EndTime

在以下情况中，格式的统一保证了适当的功能。

包含 @StartTime 和 @EndTime 的正确 SQL 查询
SELECT data_name AS dataName, value, convert(datetime, DATETIME) AS timestamp FROM table
WHERE convert(datetime, DATETIME) > @StartTime AND convert(datetime, DATETIME) < @EndTime

CSV序列化​

OIBus提供了将检索到的数据序列化为CSV文件的选项，并且您可以使用以下设置自定义序列化过程：

  • 文件名：结果将被存储的文件的名称。您可以使用若干内部变量，如@ConnectorName（连接器的名称）和@CurrentDate（当前日期，格式为yyyy_MM_dd_HH_mm_ss_SSS - 这与序列化的日期时间格式不相关，用于日期时间字段）。
  • 分隔符：CSV中使用的分隔符。
  • 压缩：选择是否使用gzip压缩文件。
  • 输出日期时间格式：指定CSV中的日期时间格式。OIBus将仅转换指定的日期时间字段。在输出文件名中使用的@CurrentDate变量不会受到影响。
  • 输出时区：用于存储日期时间的时区。

拆分大型查询​

在请求大时间间隔时，特别是当使用@StartTime和@EndTime查询变量可能对服务器造成显著负载的情况下，您可以将查询拆分为若干个具有更小间隔的子查询。这可以通过配置历史设置中的最大读取间隔字段来实现。