IoT Hub 디바이스 및 모듈 쌍에 대한 쿼리
디바이스 쌍 및 모듈 쌍은 임의의 JSON 개체를 태그와 속성으로 포함할 수 있습니다. IoT Hub를 사용하면 모든 쌍 정보를 포함하는 단일 JSON 문서로 디바이스 쌍 및 모듈 쌍을 쿼리할 수 있습니다.
다음은 샘플 IoT 허브 디바이스 쌍입니다(모듈 쌍은 moduleId에 대한 매개 변수와 유사함).
{
"deviceId": "myDeviceId",
"etag": "AAAAAAAAAAc=",
"status": "enabled",
"statusUpdateTime": "0001-01-01T00:00:00",
"connectionState": "Disconnected",
"lastActivityTime": "0001-01-01T00:00:00",
"cloudToDeviceMessageCount": 0,
"authenticationType": "sas",
"x509Thumbprint": {
"primaryThumbprint": null,
"secondaryThumbprint": null
},
"version": 2,
"tags": {
"location": {
"region": "US",
"plant": "Redmond43"
}
},
"properties": {
"desired": {
"telemetryConfig": {
"configId": "db00ebf5-eeeb-42be-86a1-458cccb69e57",
"sendFrequencyInSecs": 300
},
"$metadata": {
...
},
"$version": 4
},
"reported": {
"connectivity": {
"type": "cellular"
},
"telemetryConfig": {
"configId": "db00ebf5-eeeb-42be-86a1-458cccb69e57",
"sendFrequencyInSecs": 300,
"status": "Success"
},
"$metadata": {
...
},
"$version": 7
}
}
}
디바이스 쌍 쿼리
IoT Hub는 devices라는 문서 컬렉션으로 디바이스 쌍을 노출합니다. 예를 들어, 가장 기본적인 쿼리는 디바이스 쌍 전체 세트를 검색합니다.
SELECT * FROM devices
참고 항목
Azure IoT SDK는 큰 결과의 페이징을 지원합니다.
SELECT 절을 사용하여 쿼리 결과를 집계할 수 있습니다. 예를 들어 다음 쿼리는 IoT Hub의 총 디바이스 수를 가져옵니다.
SELECT COUNT() as totalNumberOfDevices FROM devices
WHERE 절을 사용하여 쿼리 결과를 필터링합니다. 예를 들어, location.region 태그가 US로 설정된 디바이스 쌍을 받으려면 다음 쿼리를 사용합니다.
SELECT * FROM devices
WHERE tags.location.region = 'US'
부울 연산자 및 산술 비교를 사용하여 복잡한 WHERE 절을 만듭니다. 예를 들어, 다음 쿼리는 미국에 있고 1분 미만 주기로 원격 분석을 보내도록 구성된 디바이스 쌍을 검색합니다.
SELECT * FROM devices
WHERE tags.location.region = 'US'
AND properties.reported.telemetryConfig.sendFrequencyInSecs >= 60
IN 및NIN(IN이 아님) 연산자와 함께 배열 상수를 사용할 수도 있습니다. 예를 들어, 다음 쿼리는 WiFi 또는 유선 연결을 보고하는 디바이스 쌍을 검색합니다.
SELECT * FROM devices
WHERE properties.reported.connectivity IN ['wired', 'wifi']
특정 속성을 포함하는 모든 디바이스 쌍을 식별해야 하는 경우가 종종 있습니다. IoT Hub는 이러한 용도로 is_defined() 함수를 지원합니다. 예를 들어, 다음 쿼리는 connectivity 속성을 정의하는 디바이스 쌍을 검색합니다.
SELECT * FROM devices
WHERE is_defined(properties.reported.connectivity)
필터링 기능에 대한 전체 참조는 WHERE 절 섹션을 참조하세요.
그룹화도 지원됩니다. 예를 들어, 다음 쿼리는 각 원격 분석 구성 상태의 디바이스 개수를 반환합니다.
SELECT properties.reported.telemetryConfig.status AS status,
COUNT() AS numberOfDevices
FROM devices
GROUP BY properties.reported.telemetryConfig.status
이 그룹화 쿼리는 다음 예제와 비슷한 결과를 반환합니다.
[
{
"numberOfDevices": 3,
"status": "Success"
},
{
"numberOfDevices": 2,
"status": "Pending"
},
{
"numberOfDevices": 1,
"status": "Error"
}
]
이 예제에서는 세 디바이스는 성공적인 구성을 보고하고 두 디바이스는 구성을 계속 적용하고 있으며 하나는 오류를 보고했습니다.
개발자는 프로젝션 쿼리를 사용하여 관심 있는 속성만 반환할 수 있습니다. 예를 들어 연결이 끊긴 모든 사용 디바이스의 디바이스 ID와 함께 마지막 작업 시간을 검색하려면 다음 쿼리를 사용합니다.
SELECT DeviceId, LastActivityTime FROM devices WHERE status = 'enabled' AND connectionState = 'Disconnected'
해당 쿼리의 결과는 다음 예제와 같이 표시됩니다.
[
{
"deviceId": "AZ3166Device",
"lastActivityTime": "2021-05-07T00:50:38.0543092Z"
}
]
모듈 쌍 쿼리
모듈 쌍에 대한 쿼리는 디바이스 쌍에 대한 쿼리와 유사하지만, 디바이스에서가 아니라 다른 컬렉션/네임스페이스를 사용하여 device.modules를 쿼리합니다.
SELECT * FROM devices.modules
디바이스 및 devices.modules 컬렉션 간의 조인을 허용하지 않습니다. 디바이스 간에 모듈 쌍을 쿼리하려는 경우 태그에 따라 수행합니다. 다음 쿼리는 검사 상태와 함께 모든 디바이스에서 모든 모듈 쌍을 반환합니다.
SELECT * FROM devices.modules WHERE properties.reported.status = 'scanning'
다음 쿼리는 검사 상태와 함께 모든 모듈 쌍을 반환하지만 지정된 하위 집합의 디바이스에 있는 모듈 쌍만 반환합니다.
SELECT * FROM devices.modules
WHERE properties.reported.status = 'scanning'
AND deviceId IN ['device1', 'device2']
쌍 쿼리 제한 사항
Important
쿼리 결과는 결과적으로 일관된 작업이며 최대 30분의 지연은 허용되어야 합니다. 대부분의 경우 쌍 쿼리는 몇 초 정도 결과를 반환합니다. IoT Hub는 모든 작업에 낮은 대기 시간을 제공하기 위해 노력합니다. 그러나 네트워크 상태 및 예측할 수 없는 기타 요인으로 인해 특정 대기 시간을 보장할 수 없습니다.
트윈 쿼리에 대한 대체 옵션은 get twin REST API를 사용하여 ID로 개별 디바이스 쌍을 쿼리하는 것입니다. 이 API는 항상 최신 값을 반환하며 더 높은 제한을 적용합니다. REST API를 직접 발급하거나 Azure IoT Hub Service SDK 중 하나에서 동등한 기능을 사용할 수 있습니다.
쿼리 식의 최대 길이는 8192자일 수 있습니다.
현재 비교는 기본 형식(개체 없음) 간에만 지원됩니다. 예를 들어 ... WHERE properties.desired.config = properties.reported.config는 해당 속성에 기본 값이 있는 경우에만 지원됩니다.
모든 시나리오에서 트윈 쿼리의 디바이스 ID 속성에 있는 lastActivityTime에 대한 종속성을 사용하지 않는 것이 좋습니다. 이 필드는 디바이스 상태의 정확한 게이지를 보장하지 않습니다. 대신 IoT 디바이스 수명 주기 이벤트를 사용하여 디바이스 상태 및 작업을 관리하세요. 솔루션에서 IoT Hub 수명 주기 이벤트를 사용하는 방법에 대한 자세한 내용은 작업을 트리거하기 위해 Event Grid를 사용하여 IoT Hub 이벤트에 반응을 참조하세요.
참고 항목
이 작업의 최대 대기 시간에 대해 가정하지 마세요. 대기 시간을 고려하여 솔루션을 빌드하는 방법에 대한 자세한 내용은 대기 시간 솔루션을 참조하세요.
다음 단계
- IoT Hub 쿼리 언어의 기본 사항 이해