Query Microservice
Vous pouvez utiliser Query Microservice pour décharger le serveur ThingWorx en autorisant l'exécution de requêtes dans un processus distinct sur la même machine ou sur une autre machine. L'utilisation de Query Microservice est recommandée dans les cas suivants :
• Votre système utilise des requêtes qui chargent et récupèrent une très grande quantité de données en mémoire, entraînant alors un ralentissement des performances ou un plantage du système.
• Votre système est lent ou ne répond pas en raison d'un grand nombre de requêtes exécutées dans le cadre du traitement.
 |
Bien que Query Microservice réduise le traitement système sur le serveur ThingWorx, il est toujours possible que l'exécution de requêtes pénalise le service en raison du traitement d'un très grand nombre de données.
|
Caractéristiques
• Query Microservice prend en charge les fournisseurs de données PostgreSQL, MSSQL et InfluxDB sur ThingWorx 8.4.0 et versions ultérieures.
• Query Microservice ne prend en charge que les flux de valeurs.
• Query Microservice peut être exécuté sur la même machine que ThingWorx ou sur une autre machine.
• Prise en charge du curseur de base de données : peut être activée avec l'option <queryservice.serialisation PageSize>. Lorsqu'elle est activée, les résultats d'interrogation de la base de données sont renvoyés sous forme de fragments de la taille définie et non en une seule fois. La mémoire du serveur est ainsi moins sollicitée, réduisant ainsi les risques de plantage du service. La valeur par défaut est 0, à savoir aucun curseur.
Emplacement
Query Microservice est disponible sur le·
portail de support PTC.
Installation et configuration
Pour utiliser Query Microservice, des informations d'identification de sécurité doivent être définies pour permettre la communication entre ThingWorx et Query Microservice. Pour cela, il est nécessaire d'utiliser l'
outil de gestion ThingWorx Security. Query Microservice doit être installé à l'aide des scripts fournis dans le package de distribution. Pour installer et configurer Query Microservice, procédez comme suit :
|
|
Cette procédure suppose que ThingWorx est installé. Si nécessaire, consultez la rubrique
Installation de ThingWorx.
|
2. Exécutez le programme d'installation de Query Microservice (.qms-1.0-windows-installer.exe pour Windows ou qms-1.0-linux-x64-installer.run pour Linux). L'écran du programme d'installation s'affiche. Cliquez sur Next.
|
|
Si vous utilisez Linux, le programme d'installation contient un fichier .run qui nécessite des autorisations d'exécution. Pour les définir, exécutez la commande suivante :
chmod +x qms-installer-file-name.run
|
|
|
Si vous exécutez le programme d'installation sous la forme ./qms-installer-file-name.run, il s'exécute en mode graphique. Pour l'exécuter en mode texte, exécutez la commande suivante :
./qms-installer-file-name.run --mode text
|
3. Dans le champ de répertoire d'installation, spécifiez l'emplacement d'installation. Cliquez sur Next.
4. Ajoutez l'emplacement du serveur ThingWorx et la clé d'application à laquelle se connecter. Cliquez sur Next.
5. Cliquez sur Terminer.
6. Créez un fichier de configuration Query Microservice avec les paramètres ci-après et donnez-lui un nom. Dans cet exemple, le fichier est nommé qms-security.props. Mettez à jour les valeurs pour password-file-path et path.
| | N'importe quel répertoire peut être défini pour ces emplacements. Ils doivent cependant correspondre aux valeurs du fichier application.properties de Query Microservice. Le fichier keystore.jks doit se trouver dans le répertoire path et le fichier keystore-password dans le répertoire password-file-path. Si ces répertoires n'existent pas, ils sont automatiquement créés. |
| | Exigences en matière d'autorisation : • Les répertoires doivent exister et être accessibles en écriture par l'utilisateur exécutant l'outil de gestion de la sécurité. • L'utilisateur exécutant Query Microservice doit disposer de droits d'accès en lecture. |
{
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"
}
}
}
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. Téléchargez l'outil en ligne de commande pour la gestion de la sécurité depuis le
Site de Support PTC.
| | Pour plus d'informations sur l'outil, consultez la rubrique
Outil de gestion de la sécurité. |
8. Exécutez la ligne de commande pour l'outil de sécurité avec un fichier de configuration ThingWorx pour générer la clé.
| | Dans cet exemple, la clé est nommée qmsAesEncryptionKey. |
./security-common-cli qms-security.props generate-key qmsAesEncryptionKey
9. Obtenez la clé qmsAesEncryptionKey générée en exécutant security-common-cli afin d'obtenir la clé de chiffrement générée, la copier et l'enregistrer. Elle sera insérée dans le keystore ThingWorx dans les étapes suivantes :
./security-common-cli qms-security.props get qmsAesEncryptionKey
Loading config from file qms-security.props
7qT1lf6adY+UvV8hq/xxxx==
Loading config from file qms-security.props
7qT1lf6adY+UvV8hq/xxxx==
10. Créez un fichier de configuration pour l'outil de gestion de la sécurité et donnez-lui un nom (dans cet exemple, twx-security.props). Mettez à jour les valeurs pour password-file-path et path.
| | Le fichier keystore.jks doit se trouver dans le répertoire path et le fichier keystore-password dans le répertoire password-file-path. |
| | Exigences en matière d'autorisation : • Ces répertoires doivent exister et être accessibles en écriture par l'utilisateur exécutant l'outil de gestion de la sécurité. |
{
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"
}
}
}
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. Insérez la clé qmsAesEncryptionKey dans le keystore ThingWorx :
./security-common-cli twx-security.props set qmsAesEncryptionKey OBTAINED_KEY_ABOVE
12. Vérifiez que la configuration du fichier application.properties de Query Microservice correspond à celle du fichier de configuration de l'outil de sécurité.
13. Ajoutez à application.properties la clé d'application qui vient d'être générée ou ajoutez-la au keystore de Query Microservice à l'aide de l'outil de ligne de commande. Consultez la section
Paramètres de configuration ci-dessous pour en savoir plus. Par exemple :
./security-common-cli qms-security.props set qmsThingworxAppKey <Application key>
14. Exécutez Query Microservice depuis le répertoire query-micro-service-1.0.0 à l'aide de la commande suivante :
| | Les autorisations d'exécution appropriées doivent être configurées. |
◦ Linux :
./bin/query-micro-service.sh
◦ Windows :
bin\query-micro-service
15. Si nécessaire, vérifiez que Query Microservice a été installé avec succès.
| | Le service crée dans Composer un nouvel objet nommé remoteQueryService. Tant que l'objet remoteQueryService existe sur la plateforme et que son état est Actif, les requêtes ne seront pas exécutées sur le serveur ThingWorx. Pour exécuter des requêtes sur le serveur ThingWorx, vous devez supprimer manuellement l'objet remoteQueryService. |
| | Pour vérifier que l'objet remoteQueryService est actif, vous pouvez vous référer à l'icône en regard du nom de l'entité dans Composer. Le service est connecté dans l'image ci-dessous :  Dans l'image ci-dessous, l'icône rouge indique qu'il n'est pas connecté.  |
Paramètres de configuration
Query Microservice comprend un fichier application.properties qui se trouve dans le répertoire config après extraction du fichier TAR ou ZIP fourni. Si vous n'utilisez pas les valeurs par défaut, les paramètres de configuration de Query Microservice sont répertoriés ci-dessous et doivent être configurés avant d'exécuter le service :
Paramètre | Description | Valeur par défaut |
|---|---|---|
queryserviceMinthread | Nombre minimal de threads que le client (Query Microservice) utilisera pour traiter les messages entrants. Si tous les threads sont occupés à gérer les messages, les messages entrants suivants seront placés dans une file d'attente jusqu'à ce que la limite définie par queryservice.queuesize soit atteinte. Une fois la file d'attente complète, les threads supplémentaires seront ajoutés jusqu'à atteindre la valeur définie pour queryservice.maxthread. | 4 |
queryserviceMaxthread | Nombre maximal de threads que le client (Query Microservice) utilisera pour traiter les messages entrants. | 10 |
queryserviceQueuesize | QueueSize correspond au nombre de messages entrants que peut contenir la file d'attente avant que d'autres threads ne soient ajoutés au pool de threads. Si le nombre maximal de threads actifs est atteint, les nouveaux messages entrants seront rejetés. | 1000 |
queryserviceSerialisationPageSize | Taille de récupération du curseur de base de données. Par défaut, la pagination est désactivée. La taille recommandée est 5,000. | 0 |
thingworxUri | URI et port de l'hôte du serveur ThingWorx. | ws://localhost:8080/Thingworx/WS |
qmsThingworxAppKey | Clé d'application utilisée pour la connexion au serveur ThingWorx. Elle doit être créée dans ThingWorx avant d'exécuter le microservice. |
Paramètre | Description |
|---|---|
default-encryption-key-length | Longueur par défaut utilisée pour les clés de chiffrement. |
password-file-path | Chemin d'accès absolu du fichier de mot de passe du keystore de Query Microservice. |
password-file-name | Nom du fichier de mot de passe du keystore. |
path | Chemin d'accès absolu du fichier keystore de Query Microservice. |
name | Nom du fichier keystore. |