규칙 쿼리 상세 작성 규칙

규칙 쿼리를 생성하기 위해서는 기본적인 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 필드 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 연결의 특성상 네트워크 연결이 안정적이지 않아 커넥션이 끊길수 있습니다. 재접속이 필요할 수 있습니다.

""에 대한 건이 검색되었습니다.

    ""에 대한 검색 결과가 없습니다.

    처리중...