Azure IoT Hub 원격 분석이 아닌 이벤트 스키마
이 문서에서는 Azure IoT Hub에서 내보낸 원격 분석이 아닌 이벤트에 대한 속성 및 스키마를 제공합니다. 비 원격 분석 이벤트는 IoT Hub가 디바이스와 연결된 특정 상태 변경에 대응하여 이러한 이벤트를 내보낸다는 측면에서 디바이스-클라우드 및 클라우드-디바이스 메시지와 다릅니다. 예를 들어 만들기 또는 삭제되는 디바이스 또는 모듈과 같은 수명 주기 변경 또는 디바이스 또는 모듈 연결 또는 연결 끊기와 같은 연결 상태 변경입니다.
메시지 라우팅을 사용하여 원격 분석이 아닌 이벤트를 라우팅하거나 Azure Event Grid를 사용하여 원격 분석이 아닌 이벤트에 연결할 수 있습니다. IoT Hub 메시지 라우팅에 대해 자세히 알아보려면 IoT Hub 메시지 라우팅 및 Event Grid를 사용하여 IoT Hub 이벤트에 반응을 참조하세요.
이 문서의 이벤트 예는 az iot hub monitor-events Azure CLI 명령을 사용하여 캡처되었습니다. 메시지 라우팅 엔드포인트에 도착하는 이벤트에 포함된 속성의 하위 집합을 볼 수 있습니다.
사용할 수 있는 이벤트 유형
Azure IoT Hub는 다음 범주에서 원격 분석이 아닌 이벤트를 내보냅니다.
| 이벤트 범주 | 설명 |
|---|---|
| 디바이스 연결 상태 이벤트 | 디바이스가 IoT Hub에 연결되거나 연결을 끊을 때 발생합니다. |
| 디바이스 수명 주기 이벤트 | IoT Hub에서 디바이스 또는 모듈을 만들거나 삭제할 때 발생합니다. |
| 디바이스 쌍 변경 이벤트 | 디바이스 또는 모듈 쌍이 변경되거나 교체될 때 발생합니다. |
| 디지털 쌍 변경 이벤트 | 디바이스 또는 모듈의 디지털 트윈이 변경되거나 교체될 때 발생합니다. |
일반 이벤트 속성
원격 분석이 아닌 이벤트는 몇 가지 공통 속성을 공유합니다.
시스템 속성
IoT Hub는 각 이벤트에 대해 다음 시스템 속성을 설정합니다.
| 속성 | Type | 설명 | 라우팅 쿼리를 위한 키워드 |
|---|---|---|---|
| content-encoding | string | utf-8 | $contentEncoding |
| content-type | string | application/json | $contentType |
| correlation-id | string | 이벤트를 식별하는 고유 ID입니다. | $correlationId |
| user-id | string | 이벤트를 생성한 IoT Hub의 이름입니다. | $userId |
| iothub-connection-device-id | string | 디바이스 ID | $connectionDeviceId |
| iothub-connection-module-id | string | 모듈 ID입니다. 이 속성은 모듈 수명 주기 및 쌍 이벤트에 대해서만 출력됩니다. | $connectionModuleId |
| iothub-enqueuedtime | number | 알림이 전송된 날짜 및 시간입니다. 라우팅 쿼리에서 ISO8601 타임스탬프를 사용합니다. 예: $enqueuedTime > "2022-06-06T22:56:06Z" |
$enqueuedTime |
| iothub-message-source | string | 메시지 원본을 식별하는 이벤트 범주입니다. 예: deviceLifecycleEvents. | 해당 없음 |
애플리케이션 속성
IoT Hub는 각 이벤트에 대해 다음 애플리케이션 속성을 설정합니다.
| 속성 | Type | 설명 |
|---|---|---|
| deviceId | string | 디바이스 ID |
| hubName | string | 이벤트를 생성한 IoT Hub의 이름입니다. |
| iothub-message-schema | string | 이벤트 범주와 연결된 메시지 스키마(예: deviceLifecycleNotification). |
| moduleId | string | 모듈 ID입니다. 이 속성은 모듈 수명 주기 및 쌍 변경 이벤트에 대해서만 출력됩니다. |
| operationTimestamp | string | ISO8601 작업 타임스탬프입니다. |
| opType | string | 이벤트를 생성한 작업의 식별자입니다. 예: createDeviceIdentity 또는 deleteDeviceIdentity. |
라우팅 쿼리에서 속성 이름을 사용합니다. 예: deviceId = "my-device".
연결 상태 이벤트
연결 상태 이벤트는 디바이스 또는 모듈이 IoT Hub에 연결되거나 연결을 끊을 때마다 내보내집니다.
애플리케이션 속성: 다음 표는 연결 상태 이벤트에 대해 애플리케이션 속성이 설정되는 방식을 보여 줍니다:
| 속성 | 값 |
|---|---|
| iothub-message-schema | deviceConnectionStateNotification |
| opType | deviceConnected 또는 deviceDisconnected |
모듈과 디바이스는 모두 연결 상태 이벤트를 보고하기 위해 애플리케이션 속성과 deviceDisconnected 애플리케이션 속성을 사용합니다deviceConnected. 이벤트가 모듈에서 온 경우 이벤트에는 속성도 포함됩니다 moduleId . 속성이 없 moduleId 으면 디바이스에서 이벤트가 발생합니다.
시스템 속성: 다음 표는 연결 상태 이벤트에 대해 시스템 속성이 설정되는 방식을 보여 줍니다:
| 속성 | 값 |
|---|---|
| iothub-message-source | deviceConnectionStateEvents |
본문: 본문에는 일련번호가 포함됩니다. 시퀀스 번호는 16진수 숫자에 대한 문자열 표현입니다. 문자열 비교를 사용하여 더 큰 숫자를 식별할 수 있습니다. 문자열을 16진수로 변환하면 숫자는 256비트 숫자가 됩니다. 시퀀스 번호는 엄격하게 증가하므로 최신 이벤트는 이전 이벤트보다 더 많은 수를 가집니다. 이는 디바이스 연결 및 연결이 끊어지는 경우가 자주 있고 최신 이벤트만 다운스트림 작업을 트리거하는 데 사용되도록 하려는 경우에 유용합니다.
예시
다음 JSON은 디바이스 연결이 끊길 때 발생하는 디바이스 연결 상태 이벤트를 보여 줍니다.
{
"event": {
"origin": "contoso-device-1",
"module": "",
"interface": "",
"component": "",
"properties": {
"system": {
"content_encoding": "utf-8",
"content_type": "application/json",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd",
"user_id": "contoso-routing-hub"
},
"application": {
"hubName": "contoso-routing-hub",
"deviceId": "contoso-device-1",
"opType": "deviceDisconnected",
"iothub-message-schema": "deviceConnectionStateNotification",
"operationTimestamp": "2022-06-01T18:43:04.5561024Z"
}
},
"annotations": {
"iothub-connection-device-id": "contoso-device-1",
"iothub-enqueuedtime": 1654109018051,
"iothub-message-source": "deviceConnectionStateEvents",
"x-opt-sequence-number": 72,
"x-opt-offset": "37344",
"x-opt-enqueued-time": 1654109018176
},
"payload": {
"sequenceNumber": "000000000000000001D8713FF7E0851400000002000000000000000000000007"
}
}
}
디바이스 수명 주기 이벤트
디바이스 수명 주기 이벤트는 디바이스 또는 모듈이 ID 레지스트리에서 만들어지거나 삭제될 때마다 발생합니다. 디바이스 수명 주기 이벤트가 생성되는 시기에 대한 자세한 내용은 디바이스 및 모듈 수명 주기 알림을 참조하세요.
애플리케이션 속성: 다음 표는 디바이스 수명 주기 이벤트에 대해 애플리케이션 속성이 설정되는 방식을 보여 줍니다:
| 속성 | 값 |
|---|---|
| iothub-message-schema | deviceLifecycleNotification |
| opType | 다음 값 중 하나: createDeviceIdentity, deleteDeviceIdentity. |
모듈과 디바이스는 모두 연결 상태 이벤트를 보고하기 위해 애플리케이션 속성과 deleteDeviceIdentity 애플리케이션 속성을 사용합니다createDeviceIdentity. 이벤트가 모듈에서 온 경우 이벤트에는 속성도 포함됩니다 moduleId . 속성이 없 moduleId 으면 디바이스에서 이벤트가 발생합니다.
시스템 속성: 다음 표는 디바이스 수명 주기 이벤트에 대해 시스템 속성이 설정되는 방식을 보여 줍니다:
| 속성 | 값 |
|---|---|
| iothub-message-source | deviceLifecycleEvents |
본문: 본문에는 디바이스 쌍 또는 모듈 쌍의 표현이 포함됩니다. 여기에는 디바이스 ID 및 모듈 ID, 트윈 etag, 버전 속성 및 쌍의 태그, 속성 및 관련 메타데이터가 포함됩니다.
예시
다음 JSON은 모듈이 만들어질 때 발생하는 디바이스 수명 주기 이벤트를 보여 줍니다. 이벤트는 az iot hub monitor-events Azure CLI 명령을 사용하여 캡처됩니다.
{
"event": {
"origin": "contoso-device-2",
"module": "module-1",
"interface": "",
"component": "",
"properties": {
"system": {
"content_encoding": "utf-8",
"content_type": "application/json",
"correlation_id": "c5a4e6986c",
"user_id": "contoso-routing-hub"
},
"application": {
"hubName": "contoso-routing-hub",
"deviceId": "contoso-device-2",
"operationTimestamp": "2022-05-27T18:49:38.4904785Z",
"moduleId": "module-1",
"opType": "createDeviceIdentity",
"iothub-message-schema": "deviceLifecycleNotification"
}
},
"annotations": {
"iothub-connection-device-id": "contoso-device-2",
"iothub-connection-module-id": "module-1",
"iothub-enqueuedtime": 1653677378534,
"iothub-message-source": "deviceLifecycleEvents",
"x-opt-sequence-number": 62,
"x-opt-offset": "31768",
"x-opt-enqueued-time": 1653677378643
},
"payload": {
"deviceId": "contoso-device-2",
"moduleId": "module-1",
"etag": "AAAAAAAAAAE=",
"version": 2,
"properties": {
"desired": {
"$metadata": {
"$lastUpdated": "0001-01-01T00:00:00Z"
},
"$version": 1
},
"reported": {
"$metadata": {
"$lastUpdated": "0001-01-01T00:00:00Z"
},
"$version": 1
}
}
}
}
}
디바이스 쌍 변경 이벤트
디바이스 쌍 변경 이벤트는 디바이스 쌍 또는 모듈 쌍이 업데이트되거나 교체될 때마다 내보내집니다. 경우에 따라 여러 변경 내용이 단일 이벤트에 패키지될 수 있습니다. 자세한 내용은 디바이스 쌍 백 엔드 작업 또는 모듈 쌍 백 엔드 작업을 참조하세요.
애플리케이션 속성: 다음 표는 디바이스 쌍 변경 이벤트에 대해 애플리케이션 속성이 설정되는 방식을 보여 줍니다:
| 속성 | 값 |
|---|---|
| iothub-message-schema | twinChangeNotification |
| opType | 다음 값 중 하나입니다: replaceTwin 또는 updateTwin. |
시스템 속성: 다음 표는 디바이스 쌍 변경 이벤트에 대해 시스템 속성이 설정되는 방식을 보여 줍니다:
| 속성 | 값 |
|---|---|
| iothub-message-source | twinChangeEvents |
본문: 업데이트 시 본문에는 쌍의 버전 속성, 업데이트된 태그 및 속성, 관련 메타데이터가 포함됩니다. 대체 시 본문에는 디바이스 ID 및 모듈 ID, 쌍 etag, 버전 속성 및 디바이스 또는 모듈 쌍의 모든 태그, 속성 및 관련 메타데이터가 포함됩니다.
예시
다음 JSON은 모듈 쌍의 태그 및 원하는 속성 업데이트에 대해 내보낸 쌍 변경 이벤트를 보여 줍니다. 이벤트는 az iot hub monitor-events Azure CLI 명령을 사용하여 캡처됩니다.
{
"event": {
"origin": "contoso-device-3",
"module": "module-1",
"interface": "",
"component": "",
"properties": {
"system": {
"content_encoding": "utf-8",
"content_type": "application/json",
"correlation_id": "4d1f1e2e74f",
"user_id": "contoso-routing-hub"
},
"application": {
"hubName": "contoso-routing-hub",
"deviceId": "contoso-device-3",
"operationTimestamp": "2022-06-01T22:27:50.2612586Z",
"moduleId": "module-1",
"iothub-message-schema": "twinChangeNotification",
"opType": "updateTwin"
}
},
"annotations": {
"iothub-connection-device-id": "contoso-device-3",
"iothub-connection-module-id": "module-1",
"iothub-enqueuedtime": 1654122470282,
"iothub-message-source": "twinChangeEvents",
"x-opt-sequence-number": 17,
"x-opt-offset": "12352",
"x-opt-enqueued-time": 1654122470329
},
"payload": {
"version": 7,
"tags": {
"tag1": "new value"
},
"properties": {
"desired": {
"property1": "new value",
"$metadata": {
"$lastUpdated": "2022-06-01T22:27:50.2612586Z",
"$lastUpdatedVersion": 6,
"property1": {
"$lastUpdated": "2022-06-01T22:27:50.2612586Z",
"$lastUpdatedVersion": 6
}
},
"$version": 6
}
}
}
}
}
다음 단계
메시지 라우팅에 대한 자세한 내용은 IoT Hub 메시지 라우팅을 참조하세요.
메시지 경로에 쿼리를 추가하는 방법을 알아보려면 IoT Hub 메시지 라우팅 쿼리 구문을 참조하세요.
디바이스-클라우드 및 클라우드-디바이스 메시지의 구조에 대해 알아보려면 IoT Hub 메시지 만들기 및 읽기를 참조하세요.