규칙 쿼리 상세 작성 규칙
규칙 쿼리를 생성하기 위해서는 기본적인 SQL 구문을 이해하고 있어야 하며, SELECT 구문만을 지원하므로 SELECT - FROM - WHERE 순서대로 작성해야 합니다. 규칙 쿼리 작성 규칙은 다음과 같습니다.
SELECT [<토픽 Alias>.<메시지 JSON Key1>, <토픽 Alias>.<메시지 JSON Key2>, ...] FROM "[토픽]" AS [토픽 Alias] WHERE [조건]
예시
JSON 메시지
{ "deviceId": "1", "deviceType": "illumination", "buildingId": "N1001", "roomId": "001", "light": 75, "battery": 3.3, "eventTime": "2020-01-01 00:00:00" }
조명 밝기가 50 lux 미만인 데이터의 메시지 내 모든 필드 추출
SELECT * FROM "apt/+/sensor/light" AS t WHERE t.light < 50
특정 건물의 조명 밝기가 50 lux 미만인 데이터의 메시지 내 특정 필드만 추출
SELECT t.light, t.buildingId, t.roomId, t.eventTime FROM "apt/#" AS t WHERE t.buildingId = 'N1001' AND t.light < 50
SELECT/WHERE 절
일반 SQL쿼리와 비슷하게 작성가능하며 SELECT * FROM ... 처럼 *(별표) 사용이 가능합니다.
GROUP BY / ORDER BY / DISTINCT / JOIN / UNION / UNION ALL / INTERSECT / LIMIT 등 여러 데이터를 처리하는 쿼리는 지원하지 않습니다.
SUBQUERY는 지원하지 않습니다.
MQTT로 전송한 JSON 메시지의 Key(ex: light, buildingId, ...)를 사용하여 특정 Key에 해당되는 값을 쿼리 결과로 선택할 수 있습니다.
내장 함수 또는 산술 연산식 등 JSON 필드 Key를 그대로 사용하지 않는 경우, Alias를 사용하여 결과 값으로 사용할 JSON 필드 Key를 지정하기 권장합니다. Alias가 없다면 쿼리 결과의 JSON 필드 Key는 SELECT 절에서의 위치에 따라 _1, _2, ..., _n 와 같이 출력됩니다.
예시
쿼리 (t.weight / 1000.0와 t.weight * 0.0352에는 Alias가 없어 SELECT 절의 3번째 위치는 _3, 4번째 위치는 _4로 표시됩니다.)
SELECT t.productId, t.weight AS gram, t.weight / 1000.0, t.weight * 0.0352, t.weight / 1000.0 AS kg, t.weight * 0.0352 AS oz FROM "scm/warehouse/001" AS t
결과 JSON
{ "productId":"23", "gram":1500, "_3":1.5, "_4":52.8, "kg":1.5, "oz":52.8 }
지원하는 규칙 쿼리 내장함수는 [부가기능] 페이지 규칙 쿼리 내장함수에서 확인하실 수 있습니다.
FROM 절
- 1개의 MQTT 토픽만 가능합니다.
- 토픽 이름의 최대 길이는 255자입니다.
- "(Double Quotes)를 이용하여 토픽을 감싸서 표현해야 합니다.
- SELECT 또는 WHERE 절에 토픽 이름과 동일한 JSON 필드 Key가 있을 경우, 토픽은 반드시 Alias(별칭)를 지정해야 하며, [토픽 Alias].[JSON 필드 Key] 형식으로 작성해야 합니다.
- 토픽 레벨은 /(슬래시)으로 구분해야 합니다.
- 토픽은 영문 대소문자, 숫자, 공백, !@$%^&()_-={[}]?><\/`' 의 문자를 허용합니다.
- .(마침표), *(별표), "(Double Quotes)는 토픽에 포함될 수 없습니다.
- 토픽은 / 또는 // 이 될 수 없습니다.
- 다중 레벨 와일드카드 #(해시태그)는 최종 레벨에만 사용할 수 있습니다.
- 단일 레벨 와일드카드 +(더하기)는 모든 레벨에서 사용 가능합니다.
- 와일드카드는 해당 레벨에서 단독으로 사용되어야 합니다. 다른 문자와 함께 사용할 수 없습니다.
- 규칙에 이미 등록된 메세지 재발행 액션이 있는 경우, 메세지 재발행 액션에 의해 다시 규칙 쿼리가 될 수 있는 토픽으로 설정이 불가능합니다.
기타 규칙
문자열
함수, 비교문 등에서 문자열을 사용할 경우, '(Single Quote)로 감싸줘야 합니다.
예시
JSON 메시지 deviceType 필드 값과 문자열 sensor 비교
SELECT * FROM "factory/room1/temparature" WHERE deviceType = 'sensor'
JSON 필드 Key
쿼리에서 JSON 필드 Key를 사용하지만 입력 메세지에 해당 JSON 필드 Key가 없을 경우 쿼리 에러가 발생합니다. 쿼리 에러는 에러 액션으로 확인 가능합니다.
예시
JSON 메시지 device, volt 필드 값이 없어 에러가 발생.
SELECT device FROM "factory/room1/temparature" WHERE volt = 1.5
{ "lux": 1 }
"(Double Qutoes)를 이용하여 JSON 필드 Key를 사용하고 있음을 명시적으로 나타낼 수도 있습니다. 아래 같은 경우, 반드시 필드 Key를 "(Double Qutoes)로 감싸줘야 합니다.
JSON 필드 Key의 대소문자를 구분해야할 경우
- JSON 메시지가 아래와 같다면 쿼리에서 deviceType는 대소문자 구분을 하지 않기 때문에 "(Double Qutoes)로 감싸지 않을 경우 어떤 JSON 필드 Key를 선택해야할지 알 수 없으므로 쿼리 에러가 발생합니다.
{ "deviceType": 10,"DEVICEType": 5 }
SELECT deviceType FROM "factory/room1/temparature" WHERE deviceType = 10
Multiple matches were found for the specified identifier Evaluator Error
- JSON 메시지가 아래와 같다면 쿼리에서 deviceType는 대소문자 구분을 하지 않기 때문에 "(Double Qutoes)로 감싸지 않을 경우 어떤 JSON 필드 Key를 선택해야할지 알 수 없으므로 쿼리 에러가 발생합니다.
JSON 필드 Key가 Keyword로 사용되는 단어일 경우
규칙 쿼리 검증 시, JSON 필드 Key가 쿼리문에서 사용할 수 없는 예약된 Keyword와 같으면 아래와 같은 오류가 발생합니다. Keyword와 같은 JSON 필드 Key를 사용하기 위해서는 "(Double Quotes)로 감싸서 JSON 필드 Key임을 명시해야 합니다.
Unexpected keyword
예시 (time은 쿼리문에서 Keyword이므로 "time" JSON 필드 키를 사용하기 위해 "time" 를 사용)
SELECT "time" FROM "factory/room1/temparature"
JSON 메세지 중첩 필드로 접근이 아닌 JSON 필드 Key에 .(마침표)이 포함된 경우 또는 특수문자를 포함하는 JSON 필드 Key의 경우.
규칙 쿼리에서 필드의 .(마침표)는 JSON 메시지 내 중첩 필드를 의미합니다. JSON 필드 Key에 .(마침표)이 포함된 경우, "(Double Quotes)로 감싸서 필드 Key 값의 특수문자로 처리할 수 있습니다.
예시
메시지 내용
{ "deviceId": "1", "deviceType": "sensor", "temperature": 21.3, "device.serialNo": 100001, "manufacture": { "company": "myCompany", "buildDate": "2020-01-01" } }
중첩 필드 조회
SELECT manufacture.company FROM "factory/room1/temparature"
.(마침표) 포함된 필드 조회
SELECT "device.serialNo" FROM "factory/room1/temparature"
특수문자를 포함하는 JSON 필드 Key가 있는 경우
SELECT * FROM "factory/room1/temparature" WHERE "deviceType@number" = "sensor"
제한 사항
연결 제한 사항
- 현재 MQTT 프로토콜 TLS 버젼 1.0, 1.1, 1.2 통신을 지원하며 8883 포트를 활용하여야 합니다.
메시지 제한 사항
- 메세지 토픽에 .(마침표)은 MQTT의 레벨 구분자 /(슬래쉬)의 역할을 하며, *(별표)는 MQTT의 +(와일드카드)역할을 합니다. 두 특수문자는 토픽 내 포함되지 않도록 권장드립니다.
가상 디바이스 제한 사항
- 가상 디바이스 이름은 최대 128자로 제한됩니다.
- 가상 디바이스 이름은 중복으로 등록되지 않습니다.
- 가상 디바이스 이름은 영대 소문자, 숫자, -(하이픈), _(밑줄문자)로 이루어져야 합니다.
- 속성은 최대 10개 까지 입력 가능합니다.
- 속성 Key는 중복으로 등록되지 않습니다.
- 속성 Key는 최대 128자 영대 소문자, 숫자, -(하이픈), _(밑줄문자)로 이루어져야 합니다.
- 속성 Value는 최대 512자 영대 소문자, 숫자, -(하이픈), _(밑줄문자)로 이루어져야 합니다.
속성 템플릿 제한 사항
- 속성 템플릿 이름은 중복으로 등록되지 않습니다.
- 속성 템플릿 이름은 최대 128자로 제한되며, 허용 가능한 문자는 영대 소문자, 숫자, -(하이픈), _(밑줄문자) 입니다.
- 속성 템플릿 Key는 최대 10개 까지 입력 가능합니다.
- 속성 템플릿 Key는 중복으로 등록되지 않습니다.
- 속성 Key는 최대 128자 영대 소문자, 숫자, -(하이픈), _(밑줄문자)로 이루어져야 합니다.
규칙 제한 사항
입력 제한 사항
- 규칙 이름이 같게 중복 등록되지 않습니다.
- 규칙 이름은 영대 소문자, 숫자, -(하이픈), _(밑줄문자)로 이루어져야 합니다.
- 규칙 이름은 최대 길이는 128자로 제한됩니다.
- 규칙 설명은 최대 255자로 제한됩니다.
- 규칙 쿼리는 최대 255자로 제한됩니다.
- 규칙은 사용자당 최대 100개까지 생성할 수 있습니다.
- 비활성화된 규칙일 경우 규칙과 규칙에 포함된 액션은 비활성되어 동작하지 않습니다.
- 규칙의 작성시 제한 사항은 규칙 쿼리 상세 작성 규칙을 참조하시기 바랍니다.
성능 제한 사항
- 규칙에 인입되는 메시지는 5KByte를 넘을 수 없으며 반드시 JSON 객체여야 합니다. JSON List는 지원하지 않습니다.
- 규칙에 인입되는 메시지의 토픽의 최대 길이는 255자입니다. 이 외의 메시지는 규칙 쿼리하지 않습니다.
- 규칙 처리로 인입되는 메시지는 초당 10,000개를 넘을 수 없습니다. 더 많은 인입 메세지의 경우 처리 지연이 발생합니다.
- 메시지의 규칙 처리, 액션 실행순서는 3초 내에서 순서를 보장하지 않습니다.
- 처리 지연 시간은 평균 3초이며 규칙의 개수, 쿼리의 종류, 액션의 종류에 따라 지연 시간이 추가로 발생할 수 있습니다.
액션 제한 사항
액션 종류에 따른 제한 사항
액션
- 최소 1개, 최대 5개까지 등록 가능합니다.
에러 액션
- 최대 1개 등록 가능합니다.
액션의 연동 상품별 제한 사항
지정한 토픽으로 재발행
- MQTT 재발행 액션의 토픽은 규칙 쿼리의 FROM 절의 토픽에 포함되게 설정할 수 없습니다.
- 토픽은 영문 대소문자, 숫자, 공백, !@$%^&()_-={[}]?><\/`' 의 문자를 허용합니다.
CLOUD FUNCTIONS로 데이터 전송
- Cloud Functions 상품에 등록된 트리거만 사용 가능합니다. 실제 로직을 수행하는 Cloud Functions 액션을 만들고 Cloud Functions 트리거에 반드시 연결하여야 Cloud Functions 액션을 실행할 수 있습니다.
- Cloud Functions의 트리거 중 Cloud IoT 트리거 타입의 트리거만 등록 가능합니다.
- Cloud Functions의 실행 오류 발생시 Cloud IoT Core에서 메시지 처리 지연이 발생할 수 있습니다.
- 배치 시간 설정은 최소 5초에서 최대 600초(10분)까지 지원합니다.
- Cloud Functions 액션에 전달되는 파라미터 크기는 1MB로 제한됩니다. 배치 시간 내에 해당 크기를 초과할 경우, Cloud Functions 액션을 즉시 실행합니다.
참고
- Cloud IoT Core 상품의 업데이트 시 커넥션이 끊길 수 있습니다. 커넥션이 끊기는 경우 재접속이 필요합니다.
- MQTT 연결의 특성상 네트워크 연결이 안정적이지 않아 커넥션이 끊길수 있습니다. 재접속이 필요할 수 있습니다.