디바이스 및 모듈 쌍, 작업 및 메시지 라우팅에 대한 IoT Hub 쿼리 언어
IoT Hub는 디바이스 쌍, 모듈 쌍, 작업 및 메시지 라우팅과 관련된 정보를 검색할 수 있는 강력한 SQL 유형의 언어를 제공합니다. 이 문서에 제공되는 내용:
- IoT Hub 쿼리 언어의 주요 기능 소개 및
- 언어에 대한 자세한 설명 메시지 라우팅의 쿼리 언어에 대한 자세한 내용은 메시지 라우팅의 쿼리를 참조하세요.
구체적인 예는 디바이스 및 모듈 쌍 쿼리 또는 작업 쿼리를 참조하세요.
참고 항목
클라우드-디바이스 메시지, 디바이스 트윈스, 디바이스 관리 등 이 문서에 언급된 일부 기능은 IoT Hub의 표준 계층에서만 사용할 수 있습니다. 기본 및 표준/무료 IoT Hub 계층에 대한 자세한 내용은 솔루션에 적합한 IoT Hub 계층 선택을 참조하세요.
IoT Hub 쿼리 실행
Azure Portal에서 직접 IoT 허브에 대해 쿼리를 실행할 수 있습니다.
- Azure Portal에 로그인하고 IoT Hub로 이동합니다.
- 탐색 메뉴의 디바이스 관리 섹션에서 쿼리를 선택합니다.
- 텍스트 상자에 쿼리를 입력하고 쿼리 실행을 선택합니다.
Azure IoT 서비스 SDK 및 서비스 API를 사용하여 애플리케이션 내에서 쿼리를 실행할 수도 있습니다.
IoT Hub 쿼리를 구현하는 코드 예는 서비스 SDK를 사용한 쿼리 예 섹션을 참조하세요.
SDK 참조 페이지 및 샘플에 대한 링크는 Azure IoT SDK를 참조하세요.
IoT Hub 쿼리의 기초
모든 IoT Hub 쿼리는 SELECT 및 FROM 절로 이루어지며 선택적으로 WHERE 및 GROUP BY 절이 포함됩니다.
쿼리는 디바이스 쌍과 같은 JSON 문서 컬렉션에서 실행됩니다. FROM 절은 반복이 수행될 문서 컬렉션을 나타냅니다(예: devices, 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 절
모든 ioT Hub 쿼리에는 FROM <from_specification> 절이 필요합니다. 다음 세 값 중 하나여야 합니다.
- 디바이스 쌍을 쿼리하는 디바이스
- 모듈 쌍 쿼리를 위한 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 문서의 속성을 참조합니다.
쿼리 결과 페이지 매김
query 개체는 최대 페이지 크기를 레코드 100개보다 작거나 같게 하여 인스턴스화됩니다. 여러 페이지를 얻으려면 Node.js SDK에서 nextAsTwin을 여러 번 또는 .Net SDK 메서드에서 GetNextAsTwinAsync를 여러 번 호출합니다. query 개체는 쿼리에 필요한 역직렬화 옵션에 따라 여러 개의 Next 값을 노출합니다. 예를 들어 프로젝션을 사용할 때 query 개체는 디바이스 쌍 또는 작업 개체 또는 일반 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개 이상의 유니코드 문자 시퀀스 또는 이스케이프 시퀀스로 표현되는 유니코드 문자열입니다. 문자열 리터럴은 작은 따옴표나 큰 따옴표로 묶습니다. 허용되는 이스케이프: \', \", \\, \uXXXX 4자리 16진수로 정의된 유니코드 문자용. |
연산자
다음과 같은 연산자가 지원됩니다.
| 패밀리 | 연산자 |
|---|---|
| 산술 | |
| 논리 | AND, OR, NOT |
| 비교 |
함수
쌍과 작업을 쿼리할 때 지원되는 유일한 함수는 다음과 같습니다.
| 함수 | 설명 |
|---|---|
| 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을 반환합니다. |
| STARTSWITH(x, y) | 첫 번째 문자열 식이 두 번째 문자열 식에서 시작하는지 여부를 나타내는 부울 값을 반환합니다. |
| ENDSWITH(x, y) | 첫 번째 문자열 식이 두 번째 문자열 식에서 끝나는지 여부를 나타내는 부울 값을 반환합니다. |
| CONTAINS(x,y) | 첫 번째 문자열 식이 두 번째를 포함하는지를 나타내는 부울 값을 반환합니다. |
서비스 SDK를 사용한 쿼리 예
C# 예제
쿼리 기능은 C# 서비스 SDK의 RegistryManager 클래스에서 공개합니다.
다음은 간단한 쿼리의 예입니다.
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 개체는 쿼리 결과 페이지 매김 섹션에서 언급된 매개 변수로 인스턴스화됩니다. GetNextAsTwinAsync 메서드를 여러 번 호출하여 여러 페이지가 검색됩니다.
Node.js 예제
쿼리 기능은 Node.js용 Azure IoT 서비스 SDK의 Registry 개체에서 공개됩니다.
다음은 간단한 쿼리의 예입니다.
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 개체는 쿼리 결과 페이지 매김 섹션에서 언급된 매개 변수로 인스턴스화됩니다. nextAsTwin 메서드를 여러 번 호출하여 여러 페이지가 검색됩니다.
다음 단계
- IoT Hub 메시지 라우팅 쿼리 구문을 사용하여 메시지 속성 또는 메시지 본문을 기반으로 메시지 라우팅에 대해 알아봅니다.
- 디바이스 및 모듈 쌍에 대한 쿼리 또는 작업에 대한 쿼리의 구체적인 예를 가져옵니다.