Query Microservice
È possibile utilizzare Query Microservice per scaricare il server ThingWorx consentendo l'esecuzione di interrogazioni in un processo distinto sullo stesso computer o su uno diverso. È consigliabile utilizzare Query Microservice nei casi descritti di seguito.
• Il sistema utilizza interrogazioni che caricano e recuperano una grande quantità di dati in memoria causando il rallentamento o l'arresto anomalo.
• Il sistema è lento e non risponde a causa del volume elevato di interrogazioni eseguite nell'ambito dell'elaborazione.
 |
Nonostante Query Microservice riduca l'elaborazione di sistema nel server ThingWorx, esiste comunque la possibilità che l'esecuzione di interrogazioni determini l'arresto del servizio a causa della grande quantità di dati da elaborare.
|
Funzionalità
• Query Microservice supporta i provider di dati PostgreSQL, MSSQL e InfluxDB in ThingWorx 8.4.0 e versioni successive.
• Query Microservice supporta solo stream di valori.
• Query Microservice può essere eseguito sullo stesso computer di ThingWorx o su un computer diverso.
• Supporto del cursore del database: può essere attivato tramite l'opzione <queryservice.serialisation PageSize>. Se attivato, i risultati dell'interrogazione del database vengono restituiti in blocchi di queste dimensioni invece che in una volta sola. In questo modo vi è meno carico sulla memoria del server e il rischio che il servizio si arresti in modo anomale è ridotto. L'impostazione di default è 0, il che significa nessun cursore.
Posizione
Query Microservice è disponibile nel
portale Supporto PTC.
Installazione e configurazione
Per utilizzare Query Microservice, le credenziali di protezione devono essere impostate in modo da consentire la comunicazione tra ThingWorx e Query Microservice. A questo scopo è necessario usare lo
strumento di gestione della protezione di ThingWorx. Query Microservice deve essere installato tramite gli script inclusi nel package di distribuzione. Per installare e configurare Query Microservice, attenersi alla procedura descritta di seguito.
|
|
Questa procedura presuppone che ThingWorx sia installato. Se necessario, vedere
Installazione di ThingWorx.
|
2. Eseguire il programma di installazione di Query Microservice (.qms-1.0-windows-installer.exe per Windows o qms-1.0-linux-x64-installer.run per Linux). Viene visualizzata la schermata di installazione del programma di installazione. Fare clic su Avanti.
|
|
Se si utilizza Linux, il programma di installazione contiene un file .run che richiede permessi eseguibili. Per impostarli, eseguire quanto segue:
chmod +x qms-installer-file-name.run
|
|
|
Se si esegue il programma di installazione come ./qms-installer-file-name.run, viene eseguito nella modalità grafica. Per eseguirlo nella modalità di testo, eseguire quanto segue:
./qms-installer-file-name.run --mode text
|
3. Nel campo Directory di installazione specificare il percorso di installazione. Fare clic su Avanti.
4. Aggiungere il percorso del server ThingWorx e la chiave di accesso con cui connettersi. Fare clic su Avanti.
5. Fare clic su Fine.
6. Creare un file di configurazione di Query Microservice con i parametri riportati di seguito e specificare un nome per il file. In questo esempio il file è denominato qms-security.props. Aggiornare i valori per password-file-path e path.
| | È possibile utilizzare qualsiasi directory, ma queste posizioni devono corrispondere ai valori presenti nel file application.properties di Query Microservice. Il file keystore.jks deve trovarsi nella directory path, mentre il file keystore-password deve trovarsi nella directory password-file-path. Se le directory non esistono, vengono create. |
| | Requisiti di permesso • Le directory devono esistere e devono essere accessibili in scrittura dall'utente che esegue lo strumento di gestione della protezione. • L'utente che esegue Query Microservice deve disporre dell'accesso in lettura. |
{
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. Ottenere lo strumento della riga di comando per la gestione della protezione dal
sito Supporto PTC.
8. Eseguire la riga di comando per lo strumento di gestione della protezione con un file di configurazione ThingWorx per generare la chiave.
| | In questo esempio il nome della chiave è qmsAesEncryptionKey. |
./security-common-cli qms-security.props generate-key qmsAesEncryptionKey
9. Per ottenere la chiave di crittografia qmsAesEncryptionKey generata, eseguire security-common-cli. È quindi possibile copiarla e salvarla. La chiave viene inserita nel keystore ThingWorx nei passi seguenti:
./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. Creare un file di configurazione per lo strumento di gestione della protezione e indicare un nome per il file (in questo esempio è denominato twx-security.props). Aggiornare i valori per password-file-path e path.
| | Il file keystore.jks deve trovarsi nella directory path, mentre il file keystore-password deve trovarsi nella directory password-file-path. |
| | Requisiti di permesso • Queste directory devono esistere e devono essere accessibili in scrittura dall'utente che esegue lo strumento di gestione della protezione. |
{
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. Inserire qmsAesEncryptionKey nel keystore ThingWorx:
./security-common-cli twx-security.props set qmsAesEncryptionKey OBTAINED_KEY_ABOVE
12. Verificare che la configurazione nel file application.properties di Query Microservice corrisponda alla configurazione nel file di configurazione dello strumento di gestione della protezione.
13. Aggiungere la chiave di accesso appena generata ad application.properties oppure al keystore di Query Microservice utilizzando lo strumento della riga di comando. Per ulteriori informazioni, vedere la sezione
Parametri di configurazione riportata di seguito. Ad esempio:
./security-common-cli qms-security.props set qmsThingworxAppKey <Application key>
14. Eseguire Query Microservice, che si trova nella directory query-micro-service-1.0.0, eseguendo il comando riportato di seguito.
| | Verificare che abbia i permessi eseguibili. |
◦ Linux:
./bin/query-micro-service.sh
◦ Windows:
bin\query-micro-service
15. Se necessario, verificare che Query Microservice sia stato installato correttamente.
| | Il servizio crea un nuovo oggetto in Composer denominato remoteQueryService. Finché l'oggetto remoteQueryService esiste nella piattaforma ed è nello stato Attivo, le interrogazioni non vengono eseguite sul server ThingWorx. Per eseguire le query sul server ThingWorx, è necessario eliminare manualmente l'oggetto remoteQueryService. |
| | Per verificare che l'oggetto remoteQueryService sia attivo, è possibile visualizzare l'icona accanto al nome dell'entità in Composer. Il servizio è connesso nell'immagine sottostante:  Nell'immagine sottostante, l'icona rossa indica che non è connesso.  |
Parametri di configurazione
Query Microservice include un file application.properties, che si trova nella directory config dopo l'estrazione del file TAR o ZIP fornito. Se non si utilizzano i valori di default, prima di eseguire il servizio è necessario configurare i parametri di configurazione per Query Microservice elencati di seguito:
Parametro | Descrizione | Valore di default |
|---|---|---|
queryserviceMinthread | Numero minimo di thread che il client (Query Microservice) utilizza per elaborare i messaggi in arrivo. Se tutti i thread sono impegnati a gestire i messaggi, i messaggi in arrivo aggiuntivi vengono messi in coda, fino al numero specificato da queryservice.queuesize. Una volta che la coda è piena, vengono aggiunti altri thread fino al valore definito per queryservice.maxthread. | 4 |
queryserviceMaxthread | Numero massimo di thread che il client (Query Microservice) utilizza per elaborare il messaggio in arrivo. | 10 |
queryserviceQueuesize | QueueSize è il numero di messaggi in arrivo che la coda può contenere prima che altri thread vengano aggiunti al pool di thread. Se il numero massimo di thread è già attivo, i nuovi messaggi in arrivo vengono rifiutati. | 1000 |
queryserviceSerialisationPageSize | Dimensione di recupero del cursore del database. Per default, il paging è disattivato. La dimensione consigliata è 5.000. | 0 |
thingworxUri | URI e porta dell'host del server ThingWorx. | ws://localhost:8080/Thingworx/WS |
qmsThingworxAppKey | Chiave di accesso utilizzata per connettersi al server ThingWorx. Deve essere creata in ThingWorx prima di eseguire il microservice. |
Parametro | Descrizione |
|---|---|
default-encryption-key-length | Lunghezza di default utilizzata per le chiavi di crittografia. |
password-file-path | Percorso assoluto del file della password del keystore di Query Microservice. |
password-file-name | Nome del file della password del keystore. |
path | Percorso assoluto del file keystore di Query Microservice. |
name | Nome del file del keystore. |