다음을 통해 공유

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 이벤트에 반응을 참조하세요.

참고 항목

이 작업의 최대 대기 시간에 대해 가정하지 마세요. 대기 시간을 고려하여 솔루션을 빌드하는 방법에 대한 자세한 내용은 대기 시간 솔루션을 참조하세요.

다음 단계