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(커서 없음)입니다.

위치

Query Microservice는 PTC 지원 포털에서 제공됩니다.

설치 및 구성

Query Microservice를 사용하려면 ThingWorx와 Query Microservice 간 통신을 제공하도록 보안 자격 증명을 설정해야 합니다. 이를 설정하려면 ThingWorx Security 관리 도구를 사용해야 합니다. Query Microservice는 배포 패키지에 제공된 스크립트를 사용하여 설치해야 합니다. Query Microservice를 설치하고 구성하려면 다음 단계를 수행해야 합니다.

이 프로세스에서는 ThingWorx가 설치되어 있다고 가정합니다. 필요한 경우 ThingWorx 설치를 참조하십시오.

1. PTC 지원 포털에서 Query Microservice를 얻습니다.

2. Query Microservice 설치 관리자(Windows의 경우 .qms-1.0-windows-installer.exe 또는 Linux의 경우 qms-1.0-linux-x64-installer.run)를 실행합니다. 설치 관리자 설정 화면이 표시됩니다. 다음을 클릭합니다.

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 키 저장소에 추가합니다. 자세한 내용은 아래의 구성 매개 변수를 참조하십시오. 예를 들면 다음과 같습니다.

./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 서버에 연결하는 데 사용되는 응용 프로그램 키입니다. Microservice를 실행하기 전에 ThingWorx에서 이러한 키를 만들어야 합니다.

보안 매개 변수
매개 변수	설명
default-encryption-key-length	암호화 키에 사용되는 기본 길이입니다.
password-file-path	Query Microservice 키 저장소 암호 파일의 절대 경로입니다.
password-file-name	키 저장소 암호 파일 이름입니다.
path	Query Microservice 키 저장소 파일의 절대 경로입니다.
name	키 저장소 파일 이름입니다.