IoT Hub의 디바이스 쌍 이해 및 사용
디바이스 쌍은 메타데이터, 상태 및 조건을 포함하는 디바이스의 상태 정보를 저장하는 JSON 문서입니다. Azure IoT Hub는 IoT Hub에 연결하는 디바이스마다 하나의 디바이스 쌍을 유지합니다.
참고 항목
이 문서에서 설명하는 기능은 IoT Hub의 표준 계층에서만 사용할 수 있습니다. 기본 및 표준/무료 IoT Hub 계층에 대한 자세한 내용은 솔루션에 적합한 IoT Hub 계층 선택을 참조하세요.
이 문서에서는 다음을 설명합니다.
- 디바이스 쌍의 구조: 태그, 원하는 속성 및 보고된 속성.
- 디바이스 및 백 엔드 애플리케이션이 디바이스 쌍에서 수행할 수 있는 작업입니다.
디바이스 쌍의 용도:
클라우드에서 디바이스 전용 메타데이터를 저장합니다. 예를 들어, 자동 판매기의 위치입니다.
디바이스 앱의 사용 가능한 기능 및 상태와 같은 현재 상태 정보를 보고합니다. 예를 들어 디바이스가 셀룰러 또는 WiFi를 통해 IoT Hub에 연결되어 있는지 여부.
디바이스 앱과 백 엔드 앱 간에 장기 실행 워크플로의 상태를 동기화합니다. 예를 들어 솔루션 백 엔드가 설치할 새 펌웨어 버전을 지정하고 디바이스 앱이 다양한 업데이트 프로세스 단계를 보고할 경우입니다.
디바이스 메타데이터, 구성 또는 상태를 쿼리합니다.
보고된 속성, 디바이스-클라우드 메시지 또는 파일 업로드 사용에 대한 자세한 내용은 디바이스-클라우드 통신 지침을 참조하세요.
원하는 속성, 직접 메서드 또는 클라우드-디바이스 메시지 사용에 대한 자세한 내용은 클라우드-디바이스 통신 지침을 참조하세요.
디바이스 쌍이 Azure IoT 플러그 앤 플레이 디바이스에서 사용하는 디바이스 모델과 어떻게 관련되는지 알아보려면 IoT 플러그 앤 플레이 디지털 트윈 이해를 참조하세요.
디바이스 쌍
디바이스 쌍이 저장하는 디바이스 관련 정보는:
디바이스 및 백 엔드가 디바이스 상태 및 구성 동기화에 사용할 수 있습니다.
솔루션 백 엔드는 오래 실행되는 작업을 쿼리하고 대상으로 하는 데 사용할 수 있습니다.
디바이스 쌍의 수명 주기는 해당 디바이스 ID에 연결됩니다. IoT Hub에서 디바이스 ID를 만들거나 삭제하면 디바이스 쌍이 암시적으로 만들어지거나 삭제됩니다.
디바이스 쌍은 JSON 문서이며 다음을 포함합니다.
태그. 솔루션 백 엔드에서 읽고 쓸 수 있는 JSON 문서의 섹션입니다. 태그는 디바이스 앱에 표시되지 않습니다.
desired 속성. reported 속성과 함께 디바이스 구성 또는 상황을 동기화하는 데 사용됩니다. 솔루션 백 엔드는 원하는 속성을 설정할 수 있으며 디바이스 앱에서 이를 읽을 수 있습니다. 디바이스 앱에서도 desired 속성의 변경 내용 알림을 수신할 수 있습니다.
reported 속성. desired 속성과 함께 디바이스 구성 또는 상황을 동기화하는 데 사용됩니다. 디바이스 앱은 reported 속성을 설정할 수 있으며 솔루션 백 엔드는 이를 읽고 쿼리할 수 있습니다.
디바이스 ID 속성. 디바이스 쌍 JSON 문서의 루트에는 ID 레지스트리에 포함된 해당 디바이스 ID의 읽기 전용 속성이 포함됩니다. 속성
connectionStateUpdatedTime및generationId는 포함되지 않습니다.
다음 예제에서는 디바이스 쌍 JSON 문서를 보여 줍니다.
{
"deviceId": "devA",
"etag": "AAAAAAAAAAc=",
"status": "enabled",
"statusReason": "provisioned",
"statusUpdateTime": "0001-01-01T00:00:00",
"connectionState": "connected",
"lastActivityTime": "2015-02-30T16:24:48.789Z",
"cloudToDeviceMessageCount": 0,
"authenticationType": "sas",
"x509Thumbprint": {
"primaryThumbprint": null,
"secondaryThumbprint": null
},
"version": 2,
"tags": {
"deploymentLocation": {
"building": "43",
"floor": "1"
}
},
"properties": {
"desired": {
"telemetryConfig": {
"sendFrequency": "5m"
},
"$metadata" : {...},
"$version": 1
},
"reported": {
"telemetryConfig": {
"sendFrequency": "5m",
"status": "success"
},
"batteryLevel": 55,
"$metadata" : {...},
"$version": 4
}
}
}
루트 개체에는 디바이스 ID 속성과 tags에 대한 컨테이너 개체와 reported 및 desired 속성 모두가 포함되어 있습니다. properties 컨테이너에는 디바이스 쌍 메타데이터 및 낙관적 동시성 섹션에서 설명한 몇 가지 읽기 전용 요소($metadata 및 $version)가 포함됩니다.
reported 속성 예
이전 예제에서 디바이스 쌍에 batteryLevel 속성이 포함되어 있으며 이것은 디바이스 앱에 의해 보고됩니다. 이 속성은 마지막으로 보고된 배터리 수준에 기반하여 디바이스에서 쿼리 및 작업을 가능하게 합니다. 다른 예제에는 디바이스 앱 보고 디바이스 기능 또는 연결 옵션이 포함됩니다.
참고 항목
reported 속성은 솔루션 백 엔드가 마지막으로 알려진 속성 값에 관여하는 시나리오를 간소화합니다. 솔루션 백 엔드에서 타임스탬프가 적용된 이벤트 시퀀스(예: 시계열)의 형태로 디바이스 원격 분석을 처리해야 하는 경우 디바이스-클라우드 메시지를 사용합니다.
desired 속성 예제
이전 예제에서 telemetryConfig 디바이스 쌍 desired 및 reported 속성은 솔루션 백 엔드 및 디바이스 앱에서 이 디바이스의 원격 분석 구성을 동기화하는 데 사용됩니다. 예시:
솔루션 백 엔드는 desired 구성 값으로 desired 속성을 설정합니다. 다음은 desired 속성 집합이 포함된 문서의 일부분입니다.
"desired": { "telemetryConfig": { "sendFrequency": "5m" }, ... },디바이스가 연결되면 디바이스 앱에 변경 내용이 즉시 알려집니다. 연결되지 않은 경우 디바이스 앱은 연결할 때 디바이스 재연결 흐름을 따릅니다. 그런 다음 디바이스 앱은 업데이트된 구성(또는
status속성을 사용한 오류 상태)을 보고합니다. 보고된 속성의 일부는 다음과 같습니다."reported": { "telemetryConfig": { "sendFrequency": "5m", "status": "success" } ... }솔루션 백 엔드는 디바이스 쌍을 쿼리하여 여러 디바이스의 구성 작업 결과를 추적합니다.
참고 항목
이전 코드 조각은 디바이스 구성 및 상태를 인코딩하는 한 가지 방식을 가독성을 위해 최적화해 놓은 예입니다. IoT Hub는 디바이스 쌍의 desired 및 reported 속성에 대해 특정 스키마를 적용하지 않습니다.
Important
IoT 플러그 앤 플레이는 몇 가지 추가 속성을 사용하여 원하는 속성과 보고된 속성에 대한 변경 내용을 동기화하는 스키마를 정의합니다. 솔루션에서 IoT 플러그 앤 플레이를 사용하는 경우 쌍 속성을 업데이트할 때 플러그 앤 플레이 규칙을 따라야 합니다. 자세한 내용과 예제는 IoT 플러그 앤 플레이의 쓰기 가능 속성을 참조하세요.
쌍을 사용하여 펌웨어 업데이트와 같이 오래 실행되는 작업을 동기화할 수 있습니다. 속성을 사용하여 디바이스에서 장기 실행 작업을 동기화하고 추적하는 방법에 대한 자세한 내용은 desired 속성을 사용하여 디바이스 구성을 참조하세요.
백 엔드 작업
솔루션 백 엔드는 HTTPS를 통해 공개되는 다음과 같은 원자성 작업을 사용하여 디바이스 쌍에서 작동합니다.
ID로 디바이스 쌍 검색 이 작업은 태그, desired 및 reported 시스템 속성을 포함하여 디바이스 쌍 문서를 반환합니다.
디바이스 쌍 부분 업데이트. 이 작업은 솔루션 백 엔드에서 디바이스 쌍의 태그 또는 desired 속성을 부분적으로 업데이트할 수 있도록 합니다. 부분 업데이트는 속성을 추가하거나 업데이트하는 JSON 문서로 표현됩니다.
null로 설정된 속성은 제거됩니다. 다음 예제에서는 값이{"newProperty": "newValue"}인 desired 속성을 새로 생성하고,existingProperty의 기존 값을"otherNewValue"로 덮어쓰고,otherOldProperty를 제거합니다. 기존 desired 속성이나 태그에는 변화가 발생하지 않습니다.{ "properties": { "desired": { "newProperty": { "nestedProperty": "newValue" }, "existingProperty": "otherNewValue", "otherOldProperty": null } } }desired 속성 바꾸기. 솔루션 백 엔드에서 기존의 모든 desired 속성을 완전히 덮어쓰고
properties/desired에 대해 새 JSON 문서를 대체할 수 있는 작업입니다.태그 바꾸기. 이 작업을 사용하여 솔루션 백 엔드에서 기존의 모든 태그를 완전히 덮어쓰고
tags에 대해 새 JSON 문서를 대체할 수 있습니다.쌍 알림을 받습니다. 이 작업을 통해 쌍이 수정될 때 솔루션 백 엔드는 알림을 받습니다. 이를 수행하려면 IoT 솔루션은 경로를 만들고 데이터 원본을 twinChangeEvents와 동일하게 설정해야 합니다. 기본적으로 이러한 경로가 없으므로 쌍 알림이 전송되지 않습니다. 변경 속도가 너무 높은 경우 또는 내부 오류와 같은 다른 이유로 IoT Hub는 모든 변경 내용을 포함하는 하나의 알림만을 보낼 수 있습니다. 따라서 애플리케이션에 신뢰할 수 있는 감사 및 모든 중간 상태의 로깅이 필요한 경우 디바이스-클라우드 메시지를 사용하는 것이 좋습니다. 쌍 알림 메시지에 반환되는 속성 및 본문에 대한 자세한 내용은 비원격 분석 이벤트 스키마를 참조하세요.
이전의 모든 작업은 IoT Hub에 대한 액세스 제어에서 정의된 대로 낙관적 동시성을 지원하며 ServiceConnect 사용 권한이 필요합니다.
이러한 작업 외에도 솔루션 백 엔드는 다음을 수행할 수 있습니다.
SQL 스타일 IoT Hub 쿼리 언어를 사용하여 디바이스 쌍을 쿼리합니다.
작업을 사용하여 디바이스 쌍의 큰 집합에서 작업을 수행합니다.
디바이스 작업
디바이스 앱은 다음과 같은 원자성 작업을 사용하여 디바이스 쌍에서 작동합니다.
디바이스 쌍 검색 이 작업은 현재 연결된 디바이스의 desired 및 reported 시스템 속성을 포함하는 디바이스 쌍 문서를 반환합니다. (태그는 디바이스 앱에 표시되지 않습니다.)
reported 속성 부분 업데이트. 현재 연결된 디바이스의 reported 속성을 부분적으로 업데이트할 수 있는 작업입니다. 이 작업은 desired 속성의 부분 업데이트를 사용하는 솔루션 백 엔드와 동일한 JSON 업데이트 형식을 사용합니다.
desired 속성 관찰. 현재 연결된 디바이스는 desired 속성에 대한 업데이트가 발생하면 알림을 받도록 선택할 수 있습니다. 디바이스는 솔루션 백 엔드에 의해 실행된 것과 같은 형태의 업데이트(부분 또는 전체 바꾸기)를 수신합니다.
이전의 모든 작업에는 IoT Hub에 대한 액세스 제어에서 정의한 대로 DeviceConnect 사용 권한이 필요합니다.
Azure IoT 디바이스 SDK를 사용하면 이전 작업을 다양한 언어와 플랫폼에서 손쉽게 사용할 수 있습니다. desired 속성 동기화를 위한 IoT Hub 기본 형식에 대한 자세한 내용은 디바이스 다시 연결 흐름을 참조하세요.
태그 및 속성 형식
태그, desired 속성 및 reported 속성은 JSON 개체이며 다음과 같은 제한 사항이 있습니다.
키: JSON 개체의 모든 키는 UTF-8로 인코드되고 대/소문자를 구분하며 길이가 최대 1KB입니다. 허용되는 문자에서 유니코드 제어 문자(세그먼트 C0 및 C1) 및
.,$및 SP는 제외됩니다.참고 항목
메시지 라우팅에 사용되는 IoT Hub 쿼리는 키 이름의 일부로 공백 또는 문자
()<>@,;:\"/?={}를 지원하지 않습니다.값: JSON 개체의 모든 값은 부울, 숫자, 문자열, 개체와 같은 JSON 형식이 될 수 있습니다. 배열도 지원됩니다.
정수는 최솟값이 -4503599627370496이고, 최댓값이 4503599627370495입니다.
문자열 값은 UTF-8로 인코드되고 최대 4KB의 길이를 가질 수 있습니다.
깊이: 태그, desired 속성 및 reported 속성에서 JSON 개체의 최대 깊이는 10입니다. 예를 들어 다음 개체는 유효합니다.
{ ... "tags": { "one": { "two": { "three": { "four": { "five": { "six": { "seven": { "eight": { "nine": { "ten": { "property": "value" } } } } } } } } } } }, ... }
디바이스 쌍 크기
IoT Hub는 tags 값에 8KB 크기 제한을 적용하고 properties/desired 및 properties/reported 값에 32KB 크기 제한을 적용합니다. 합계는 $version 및 $metadata/$lastUpdated 등의 읽기 전용 요소를 제외합니다.
쌍 크기는 다음과 같이 계산됩니다.
JSON 문서의 각 속성에 대해 IoT Hub는 누적 계산을 통해 속성의 키와 값의 길이를 추가합니다.
속성 키는 UTF8로 인코드된 문자열로 간주됩니다.
단순 속성 값은 UTF8로 인코드된 문자열, 숫자 값(8바이트) 또는 부울 값(4바이트)으로 간주됩니다.
UTF8로 인코드된 문자열의 크기는 유니코드 제어 문자(세그먼트 C0 및 C1)를 제외한 모든 문자를 계수하여 계산됩니다.
복합 속성 값(중첩된 개체)은 속성 키 및 속성 키에 포함된 속성 값의 집계 크기를 기준으로 계산됩니다.
IoT Hub는 한도 이상으로 tags, properties/desired 또는 properties/reported 문서의 크기를 증가시키는 모든 작업을 오류와 함께 거부합니다.
디바이스 쌍 메타데이터
IoT Hub는 디바이스 쌍 desired 또는 reported 속성의 각 JSON 개체에 대한 마지막 업데이트의 타임스탬프를 유지합니다. 타임스탬프는 UTC 형식이며 ISO8601 형식 YYYY-MM-DDTHH:MM:SS.mmmZ로 인코딩됩니다.
예를 들면 다음과 같습니다.
{
...
"properties": {
"desired": {
"telemetryConfig": {
"sendFrequency": "5m"
},
"$metadata": {
"telemetryConfig": {
"sendFrequency": {
"$lastUpdated": "2016-03-30T16:24:48.789Z"
},
"$lastUpdated": "2016-03-30T16:24:48.789Z"
},
"$lastUpdated": "2016-03-30T16:24:48.789Z"
},
"$version": 23
},
"reported": {
"telemetryConfig": {
"sendFrequency": "5m",
"status": "success"
},
"batteryLevel": "55%",
"$metadata": {
"telemetryConfig": {
"sendFrequency": {
"$lastUpdated": "2016-03-31T16:35:48.789Z"
},
"status": {
"$lastUpdated": "2016-03-31T16:35:48.789Z"
},
"$lastUpdated": "2016-03-31T16:35:48.789Z"
},
"batteryLevel": {
"$lastUpdated": "2016-04-01T16:35:48.789Z"
},
"$lastUpdated": "2016-04-01T16:24:48.789Z"
},
"$version": 123
}
}
...
}
이 정보는 개체 키를 제거하는 업데이트를 유지하기 위해서 모든 수준(JSON 구조의 수준뿐만 아니라)에서 유지됩니다.
낙관적 동시성
태그, desired 속성 및 reported 속성은 모두 낙관적 동시성을 지원합니다. 쌍 속성 업데이트의 순서를 보장해야 하는 경우 다음 업데이트를 보내기 전에 reported 속성 콜백을 대기하여 애플리케이션 수준에서 동기화를 구현하는 것이 좋습니다.
디바이스 쌍에는 RFC7232에 따라 쌍의 JSON 표현을 나타내는 ETag 속성 etag가 있습니다. 일관성을 보장하기 위해 솔루션 백 엔드의 조건부 업데이트 작업에 etag 속성을 사용할 수 있습니다. 이 속성은 tags 컨테이너와 관련된 작업의 일관성을 보장하기 위한 유일한 옵션입니다.
디바이스 쌍 desired 및 reported 속성에도 증분될 수 있는 $version 값이 있습니다. ETag와 마찬가지로 버전은 업데이트의 일관성을 유지하는 파티를 업데이트하여 사용할 수 있습니다. 예를 들어 reported 속성에 대한 디바이스 앱이나 desired 속성에 대한 솔루션 백 엔드입니다.
버전은 관찰 에이전트(예: desired 속성을 관찰하는 디바이스 앱)가 업데이트 알림과 검색 작업의 결과 간에 속도를 중재해야 하는 경우에도 유용합니다. 디바이스 다시 연결 흐름 섹션에는 자세한 정보가 있습니다.
디바이스 다시 연결 흐름
IoT Hub는 연결되지 않은 디바이스에 대한 desired 속성 업데이트 알림을 유지하지 않습니다. 연결 중인 디바이스는 완전한 desired 속성 문서를 가져와야 하고 또한 업데이트 알림을 구독해야 합니다. 업데이트 알림과 전체 검색이 서로 경쟁할 가능성이 있으므로 다음과 같은 흐름을 따라야 합니다.
- 디바이스 앱을 IoT hub에 연결합니다.
- 디바이스 앱이 desired 속성 업데이트 알림을 구독합니다.
- 디바이스 앱이 desired 속성에 대한 전체 문서를 검색합니다.
디바이스 앱은 검색이 완료된 문서의 버전보다 작거나 같은 $version이 포함된 모든 알림을 무시할 수 있습니다. 이 방법은 IoT Hub가 버전이 항상 증가한다는 것을 보장하기 때문에 가능합니다.
다음 단계
이 문서에서 설명한 일부 개념을 시도해 보려면 다음과 같은 IoT Hub 문서를 참조하세요.