디바이스 및 모듈 쌍, 작업 및 메시지 라우팅에 대한 IoT Hub 쿼리 언어

IoT Hub는 디바이스 쌍, 모듈 쌍, 작업메시지 라우팅과 관련된 정보를 검색할 수 있는 강력한 SQL 유형의 언어를 제공합니다. 이 문서에 제공되는 내용:

  • IoT Hub 쿼리 언어의 주요 기능 소개 및
  • 언어에 대한 자세한 설명 메시지 라우팅의 쿼리 언어에 대한 자세한 내용은 메시지 라우팅의 쿼리를 참조하세요.

특정 예제는 디바이스 및 모듈 쌍에 대한 쿼리 또는 작업에 대한 쿼리를 참조하세요.

참고

클라우드-디바이스 메시지, 디바이스 트윈스, 디바이스 관리 등 이 문서에 언급된 일부 기능은 IoT Hub의 표준 계층에서만 사용할 수 있습니다. 기본 및 표준/무료 IoT Hub 계층에 대한 자세한 내용은 솔루션에 적합한 IoT Hub 계층 선택을 참조하세요.

IoT Hub 쿼리 실행

Azure Portal 직접 IoT Hub에 대해 쿼리를 실행할 수 있습니다.

  1. Azure Portal에 로그인하고 IoT Hub로 이동합니다.
  2. 탐색 메뉴의 디바이스 관리 섹션에서 쿼리를 선택합니다.
  3. 텍스트 상자에 쿼리를 입력하고 쿼리 실행을 선택합니다.

Azure IoT 서비스 SDK 및 서비스 API를 사용하여 애플리케이션 내에서 쿼리를 실행할 수도 있습니다.

IoT Hub 쿼리를 구현하는 예제 코드는 서비스 SDK를 사용하여 쿼리 예제 섹션을 참조하세요.

SDK 참조 페이지 및 샘플에 대한 링크는 Azure IoT SDK를 참조하세요.

IoT Hub 쿼리의 기초

모든 IoT Hub 쿼리는 SELECT 및 FROM 절로 이루어지며 선택적으로 WHERE 및 GROUP BY 절이 포함됩니다.

쿼리는 JSON 문서 컬렉션(예: 디바이스 쌍)에서 실행됩니다. FROM 절은 디바이스, devices.modules 또는 devices.jobs 중 하나에서 반복할 문서 컬렉션을 나타냅니다.

그런 다음 WHERE 절의 필터가 적용됩니다. 집계를 사용할 경우 이 단계의 결과는 GROUP BY 절에 지정된 대로 그룹화됩니다. 각 그룹에 대해 SELECT 절에 지정된 대로 행이 생성됩니다.

SELECT <select_list>
  FROM <from_specification>
  [WHERE <filter_condition>]
  [GROUP BY <group_specification>]

SELECT 절

SELECT <select_list> 절은 모든 IoT Hub 쿼리에 필요합니다. 쿼리에서 검색되는 값을 지정합니다. 새 JSON 개체를 생성하는 데 사용될 JSON 값을 지정합니다. FROM 컬렉션의 필터링된(그리고 선택적으로 그룹화된) 하위 집합의 각 요소에 대해 프로젝션 단계는 새 JSON 개체를 생성합니다. 이 개체는 SELECT 절에 지정된 값으로 구성됩니다.

예를 들면 다음과 같습니다.

  • 모든 값 반환

    SELECT *
    
  • 특정 속성 반환

    SELECT DeviceID, LastActivityTime
    
  • 쿼리 결과를 집계하여 개수를 반환합니다.

    SELECT COUNT() as TotalNumber
    

현재 SELECT 와 다른 선택 절은 디바이스 쌍의 집계 쿼리에서만 지원됩니다.

다음 구문은 SELECT 절의 문법입니다.

SELECT [TOP <max number>] <projection list>

<projection_list> ::=
    '*'
    | <projection_element> AS alias [, <projection_element> AS alias]+

<projection_element> :==
    attribute_name
    | <projection_element> '.' attribute_name
    | <aggregate>

<aggregate> :==
    count()
    | avg(<projection_element>)
    | sum(<projection_element>)
    | min(<projection_element>)
    | max(<projection_element>)

Attribute_name은 FROM 컬렉션에 있는 JSON 문서의 속성을 참조합니다.

FROM 절

FROM <from_specification> 절은 모든 ioT Hub 쿼리에 필요합니다. 다음 세 가지 값 중 하나여야 합니다.

  • 디바이스 쌍을 쿼리하는 디바이스
  • devices.modules - 모 듈 쌍 쿼리
  • 디바이스 별 작업 세부 정보를 쿼리하는 devices.jobs

예를 들면 다음과 같습니다.

  • 모든 디바이스 쌍 검색

    SELECT * FROM devices
    

WHERE 절

WHERE <filter_condition> 절은 선택 사항입니다. FROM 컬렉션의 JSON 문서가 결과의 일부로 포함되기 위해 충족해야 하는 하나 이상의 조건을 지정합니다. JSON 문서가 결과에 포함되려면 지정된 조건을 "true"로 평가해야 합니다.

예를 들면 다음과 같습니다.

  • 특정 디바이스를 대상으로 하는 모든 작업 검색

    SELECT * FROM devices.jobs
      WHERE devices.jobs.deviceId = 'myDeviceId'
    

허용되는 조건은 식 및 조건 섹션에 설명되어 있습니다.

GROUP BY 절

GROUP BY <group_specification> 절은 선택 사항입니다. 이 절은 WHERE 절에 지정된 필터 뒤와 SELECT에 지정된 프로젝션 이전에 실행됩니다. 특성의 값을 기반으로 문서를 그룹화합니다. 이러한 그룹은 SELECT 절에 지정된 대로 집계된 값을 생성하는 데 사용됩니다.

예를 들면 다음과 같습니다.

  • 각 원격 분석 구성 상태를 보고하는 디바이스 수를 반환합니다.

    SELECT properties.reported.telemetryConfig.status AS status,
      COUNT() AS numberOfDevices
    FROM devices
    GROUP BY properties.reported.telemetryConfig.status
    

현재 GROUP BY 절은 디바이스 쌍을 쿼리하는 경우에만 지원됩니다.

중요

용어 group은 현재 쿼리에서 특수 키워드로 취급됩니다. 이 경우 속성 이름으로 group을 사용하고 오류를 방지하기 위해 이중 괄호를 사용하여 묶는 것이 좋습니다. 예를 들면 SELECT * FROM devices WHERE tags.[[group]].name = 'some_value'입니다.

GROUP BY에 대한 형식 구문:

GROUP BY <group_by_element>
<group_by_element> :==
    attribute_name
    | < group_by_element > '.' attribute_name

Attribute_name은 FROM 컬렉션에 있는 JSON 문서의 속성을 참조합니다.

식 및 조건

높은 수준에서 은:

  • JSON 형식(예: 부울, 숫자, 문자열, 배열 또는 개체)의 인스턴스로 평가됩니다.
  • 기본 제공되는 연산자와 함수를 사용하여 상수 및 디바이스 JSON 문서에서 오는 조작 데이터에 의해 정의됩니다.

조건은 부울 값으로 평가되는 식입니다. 부울 true와는 다른 상수는 false로 간주됩니다. 이 규칙에는 null, 정의되지 않음, 개체 또는 배열 인스턴스, 문자열 및 부울 false가 포함됩니다.

식에 대한 구문:

<expression> ::=
    <constant> |
    attribute_name |
    <function_call> |
    <expression> binary_operator <expression> |
    <create_array_expression> |
    '(' <expression> ')'

<function_call> ::=
    <function_name> '(' expression ')'

<constant> ::=
    <undefined_constant>
    | <null_constant>
    | <number_constant>
    | <string_constant>
    | <array_constant>

<undefined_constant> ::= undefined
<null_constant> ::= null
<number_constant> ::= decimal_literal | hexadecimal_literal
<string_constant> ::= string_literal
<array_constant> ::= '[' <constant> [, <constant>]+ ']'

식 구문의 각 기호가 나타내는 의미를 이해하려면 다음 테이블을 참조하세요.

기호 정의
attribute_name FROM 컬렉션에 있는 JSON 문서의 모든 속성입니다.
binary_operator 연산자 섹션에서 나열한 모든 이항 연산자입니다.
function_name 함수 섹션에서 나열한 모든 함수입니다.
decimal_literal 소수 표기법으로 표현되는 부동 float입니다.
hexadecimal_literal 뒤에 16진수 문자열이 붙는 '0x' 문자열로 표현되는 숫자입니다.
string_literal 0개 이상의 유니코드 문자 또는 이스케이프 시퀀스 시퀀스로 표현되는 유니코드 문자열입니다. 문자열 리터럴은 작은 따옴표나 큰 따옴표로 묶습니다. 허용되는 이스케이프: \'16진수 4개로 정의된 유니코드 문자의 경우 , \", \\, \uXXXX 입니다.

연산자

다음과 같은 연산자가 지원됩니다.

패밀리 연산자
산술 +, -, *, /, %
논리 AND, OR, NOT
비교 =, !=, <, >, <=, >=, <>

Functions

쌍과 작업을 쿼리할 때 지원되는 유일한 함수는 다음과 같습니다.

함수 설명
IS_DEFINED(속성) 속성에 값(null 포함)이 할당되었는지 여부를 나타내는 부울 값을 반환합니다.

경로 조건에서 지원되는 수학 함수는 다음과 같습니다.

함수 설명
ABS(x) 지정한 숫자 식의 절대(양수) 값을 반환합니다.
EXP(x) 지정한 숫자 식(e^x)의 지수 값을 반환합니다.
POWER(x,y) 지정한 식의 값을 지정한 거듭제곱(x^y)으로 반환합니다.
SQUARE(x) 지정한 숫자 값의 제곱을 반환합니다.
CEILING(x) 지정한 숫자 식보다 크거나 같은 가장 작은 정수 값을 반환합니다.
FLOOR(x) 지정된 숫자 식보다 작거나 같은 최대 정수를 반환합니다.
SIGN(x) 지정한 숫자 식의 양수(+1), 0(0) 또는 음수(-1) 부호를 반환합니다.
SQRT(x) 지정된 숫자 값의 제곱근을 반환합니다.

경로 조건에서 지원되는 형식 검사 및 캐스팅 함수는 다음과 같습니다.

함수 설명
AS_NUMBER 입력 문자열을 숫자로 변환합니다. noop 입력이 숫자이면 이고, Undefined 문자열이 숫자를 나타내지 않으면 입니다.
IS_ARRAY 지정한 식의 형식이 배열인지 여부를 나타내는 부울 값을 반환합니다.
IS_BOOL 지정한 식의 형식이 부울인지 여부를 나타내는 부울 값을 반환합니다.
IS_DEFINED 속성이 값을 할당할지를 나타내는 부울 값을 반환합니다. 이 함수는 값이 기본 형식인 경우에만 지원됩니다. 기본 형식에는 문자열, 부울, 숫자 또는 null이 포함됩니다. DateTime, 개체 형식 및 배열은 지원되지 않습니다.
IS_NULL 지정한 식의 형식이 널인지 여부를 나타내는 부울 값을 반환합니다.
IS_NUMBER 지정한 식의 형식이 숫자인지 여부를 나타내는 부울 값을 반환합니다.
IS_OBJECT 지정한 식의 형식이 JSON 개체인지 여부를 나타내는 부울 값을 반환합니다.
IS_PRIMITIVE 지정한 식의 형식이 기본 형식(문자열, 부울, 숫자 또는 null)인지 여부를 나타내는 부울 값을 반환합니다.
IS_STRING 지정한 식의 형식이 문자열인지 여부를 나타내는 부울 값을 반환합니다.

경로 조건에서 지원되는 문자열 함수는 다음과 같습니다.

함수 설명
CONCAT(x, y, …) 둘 이상의 문자열 값을 연결한 결과인 문자열을 반환합니다.
LENGTH(x) 지정한 문자열 식의 문자 수를 반환합니다.
LOWER(x) 대문자 데이터를 소문자로 변환한 후에 문자열 식을 반환합니다.
UPPER(x) 소문자 데이터를 대문자로 변환한 후에 문자열 식을 반환합니다.
SUBSTRING(string, start [, length]) 지정한 문자 0 기준 위치에서 시작하여 지정한 길이 또는 문자열의 끝까지에 이르는 문자열 식의 일부를 반환합니다.
INDEX_OF(string, fragment) 첫 번째 지정된 문자열 식 내에서 두 번째 문자열 식이 처음 나타나는 시작 위치를 반환하거나 문자열을 찾을 수 없는 경우 -1을 반환합니다.
STARTS_WITH(x, y) 첫 번째 문자열 식이 두 번째 문자열 식에서 시작하는지 여부를 나타내는 부울 값을 반환합니다.
ENDS_WITH(x, y) 첫 번째 문자열 식이 두 번째 문자열 식에서 끝나는지 여부를 나타내는 부울 값을 반환합니다.
CONTAINS(x,y) 첫 번째 문자열 식이 두 번째를 포함하는지를 나타내는 부울 값을 반환합니다.

서비스 SDK를 사용하여 예제 쿼리

C# 예제

쿼리 기능은 C# 서비스 SDKRegistryManager 클래스에서 공개합니다.

다음은 간단한 쿼리의 예입니다.

var query = registryManager.CreateQuery("SELECT * FROM devices", 100);
while (query.HasMoreResults)
{
    var page = await query.GetNextAsTwinAsync();
    foreach (var twin in page)
    {
        // do work on twin object
    }
}

query 개체는 페이지 크기로 인스턴스화됩니다(최대 100). 그런 후 GetNextAsTwinAsync 메서드를 여러 번 호출하여 여러 페이지가 검색됩니다.

query 개체는 쿼리에 필요한 역직렬화 옵션에 따라 여러 개의 Next 값을 노출합니다. 프로젝션을 사용할 경우의 디바이스 쌍이나 작업 개체 또는 일반 JSON을 예로 들 수 있습니다.

Node.js 예제

쿼리 기능은 Node.js용 Azure IoT 서비스 SDKRegistry 개체에서 공개합니다.

다음은 간단한 쿼리의 예입니다.

var query = registry.createQuery('SELECT * FROM devices', 100);
var onResults = function(err, results) {
    if (err) {
        console.error('Failed to fetch the results: ' + err.message);
    } else {
        // Do something with the results
        results.forEach(function(twin) {
            console.log(twin.deviceId);
        });

        if (query.hasMoreResults) {
            query.nextAsTwin(onResults);
        }
    }
};
query.nextAsTwin(onResults);

query 개체는 페이지 크기로 인스턴스화됩니다(최대 100). 그런 후 nextAsTwin 메서드를 여러 번 호출하여 여러 페이지가 검색됩니다.

query 개체는 쿼리에 필요한 역직렬화 옵션에 따라 여러 개의 Next 값을 노출합니다. 프로젝션을 사용할 경우의 디바이스 쌍이나 작업 개체 또는 일반 JSON을 예로 들 수 있습니다.

다음 단계