Query Microservice

Composer 中的 ThingWorx 模型定义 > 数据存储 > 值流 > Query Microservice

Query Microservice

可使用 Query Microservice 来卸载 ThingWorx 服务器，方法是允许在相同或不同物理计算机上的独立进程中执行查询。建议在下列情况中使用 Query Microservice：

• 您的系统使用查询加载并检索了大量内存中的数据，从而导致运行速度缓慢或系统崩溃。

• 由于在处理过程中执行了大量查询，从而导致系统运行速度缓慢以及无响应。

Query Microservice 会降低 ThingWorx 服务器上的系统处理速度，此外，查询的执行还可能因数据处理量较大而导致服务中断。

功能

• Query Microservice 支持 ThingWorx 8.4.0 或更高版本中的 PostgreSQL、MSSQL 和 InfluxDB 数据提供工具。

• Query Microservice 仅支持值流。

• Query Microservice 既可在与 ThingWorx 相同的计算机上执行，也可在与其不同的计算机上执行。

• 数据库光标支持：可通过 <queryservice.serialisation PageSize> 选项启用。启用后，数据库的查询结果将以此大小的区块返回，而非一次性返回。这不但减少了服务器内存的负载，还降低了服务器中断的可能性。默认值为 0，表示无光标。

位置

可通过 PTC 支持门户获得 Query Microservice。

安装和配置

要使用 Query Microservice，就必须设置安全凭据以提供 ThingWorx 和 Query Microservice 之间的通信。这需要用到 ThingWorx 安全管理工具。必须使用发布包中提供的脚本安装 Query Microservice。应遵循以下步骤安装和配置 Query Microservice：

此过程假定 ThingWorx 已安装。如有必要，请参阅安装 ThingWorx。

1. 从 PTC 支持门户获取 Query Microservice。

2. 运行 Query Microservice 安装程序 (.qms-1.0-windows-installer.exe 适用于 Windows，qms-1.0-linux-x64-installer.run 适用于 Linux)。随即会显示安装程序设置屏幕。单击“下一步”。

若使用 Linux，则安装程序中将包含需要可执行权限的 .run 文件。要对上述内容进行设置，请运行：

chmod +x qms-installer-file-name.run

若您以 ./qms-installer-file-name.run 形式运行安装程序，那么它将以图形模式运行。要以文本模式运行，请运行：

./qms-installer-file-name.run --mode text

3. 请在安装目录字段中指定安装位置。单击“下一步”。

4. 添加 ThingWorx 服务器的位置以及要连接的应用程序密钥。单击“下一步”。

5. 单击“完成”。

6. 使用下列参数创建 Query Microservice 配置文件，并提供文件名。在此示例中，文件名为 qms-security.props。更新 password-file-path 和 path 的值。

这些位置可以是任意目录，但必须与 Query Microservice application.properties 文件中的值相匹配。keystore.jks 文件应位于 path 目录下，keystore-password 文件应位于 password-file-path 目录下。当它们不存在时需要予以创建。

权限要求：

• 目录必须存在，且必须能由运行安全管理工具的用户写入。

• 运行 Query Microservice 的用户必须具有读取访问权限。

{
security {
secret-provider = "com.thingworx.security.provider.keystore.KeyStoreProvider"
default-encryption-key-length = 128
keystore {
password-file-path = "/QmsPasswordDir"
password-file-name = "qms-keystore-password"
path = "/QmsKeysotreDir"
name = "qmskeystore.jks"
}
}
}

7. 从 PTC 支持网站获取安全管理命令行工具。

有关该工具的详细信息，请参阅安全管理工具。

8. 使用 ThingWorx 配置文件运行安全工具的命令行以生成密钥。

本示例中，密钥名称为 qmsAesEncryptionKey。

./security-common-cli qms-security.props generate-key qmsAesEncryptionKey

9. 通过运行 security-common-cli 获取生成的 qmsAesEncryptionKey 密钥，进而获取生成的加密密钥，然后复制并保存该密钥。通过以下步骤将其插入 ThingWorx 密钥库：

./security-common-cli qms-security.props get qmsAesEncryptionKey

Loading config from file qms-security.props
7qT1lf6adY+UvV8hq/xxxx==

10. 为安全管理工具创建配置文件并为该文件提供名称 (本示例将其命名为 twx-security.props)。更新 password-file-path 和 path 的值。

keystore.jks 文件应位于 path 目录下，keystore-password 文件应位于 password-file-path 目录下。

权限要求：

• 这些目录必须存在，且必须能由同您一起运行安全管理工具的用户写入。

{
security {
secret-provider = "com.thingworx.security.provider.keystore.KeyStoreProvider"
default-encryption-key-length = 128

keystore {
password-file-path = "/ThingworxPlatform"
password-file-name = "keystore-password"
path = "/ThingworxStorage"
name = "keystore.jks"
}
}
}

11. 将 qmsAesEncryptionKey 插入 ThingWorx 密钥库：

./security-common-cli twx-security.props set qmsAesEncryptionKey OBTAINED_KEY_ABOVE

12. 验证 Query Microservice application.properties 文件中的配置是否与安全工具配置文件中的配置相匹配。

13. 将新生成的应用程序密钥添加至 application.properties，或通过命令行工具将其添加至 Query Microservice keystore。有关详细信息，请参阅下文的配置参数。例如：

./security-common-cli qms-security.props set qmsThingworxAppKey <Application key>

14. 通过执行以下内容来运行位于 query-micro-service-1.0.0 目录中的 Query Microservice：

验证其是否具备可执行程序的权限。

◦ Linux：

./bin/query-micro-service.sh

◦ Windows：

bin\query-micro-service

15. 如有必要，请验证 Query Microservice 是否已成功安装。

该服务在 Composer 中创建了一个名为 remoteQueryService 的新事物。只要平台中存在 remoteQueryService 事物且该事物处于活动状态，就不会在 ThingWorx 服务器上执行查询。要在 ThingWorx 服务器上执行查询，就必须手动删除 remoteQueryService 事物。

要验证 remoteQueryService 事物是否处于活动状态，可在 Composer 中查看实体名称旁的图标。服务连接如下图所示：

在下图中，红色图标表示未连接。

配置参数

在提取所提供的 TAR 或 ZIP 文件后，Query Microservice 将包含一个位于 config 目录下的 application.properties 文件。如果未使用默认值，则 Query Microservice 的配置参数如下表所示，且必须在服务运行前进行配置：

参数	说明	默认值
queryserviceMinthread	客户端 (Query Microservice) 用于处理传入消息的最小线程数。如果所有线程均被占用且正在处理消息，那么其他传入消息将排队等候 (最多不超过 queryservice.queuesize 所指定的数目)。队列填满后，将添加其他线程 (最多不超过为 queryservice.maxthread 所定义的值)。	4
queryserviceMaxthread	客户端 (Query Microservice) 用于处理传入消息的最大线程数。	10
queryserviceQueuesize	QueueSize 表示在将更多线程添加至线程池前队列可容纳的最大传入消息数。如果最大线程数已处于活动状态，则新传入的消息将被拒绝。	1000
queryserviceSerialisationPageSize	数据库光标获取大小。默认值为禁用分页。建议大小为 5000。	0
thingworxUri	ThingWorx 服务器主机 URI 和端口。	ws://localhost:8080/Thingworx/WS
qmsThingworxAppKey	用于连接 ThingWorx 服务器的应用程序密钥。必须在运行微服务前于 ThingWorx 中创建该密钥。

安全参数
参数	说明
default-encryption-key-length	用于加密密钥的默认长度。
password-file-path	Query Microservice keystore 密码文件的绝对路径。
password-file-name	密钥库密码文件名。
path	Query Microservice keystore 文件的绝对路径。
name	密钥库文件名。