IoT Hub 데이터 연결

아티클
04/06/2023

클라우드에서 호스팅되는 관리형 서비스인 Azure IoT Hub는 IoT 애플리케이션과 관리하는 디바이스 간의 양방향 통신을 위한 중앙 메시지 허브의 역할을 합니다. Azure Data Explorer는 디바이스-클라우드 메시지의 엔드포인트에 기본 제공된 Event Hub 호환을 사용하여 고객 관리 IoT Hub에서 지속적인 수집을 제공합니다.

IoT 수집 파이프라인은 여러 단계를 거칩니다. 먼저 IoT Hub를 만들고 여기에 디바이스를 등록합니다. 그런 다음 Azure Data Explorer에서 특정 형식의 데이터가 지정된 수집 속성을 사용하여 수집될 대상 테이블을 만듭니다. IoT Hub를 연결하려면 Azure Data Explorer 테이블에 연결하기 위해 이벤트 라우팅을 알아야 합니다. 데이터는 이벤트 시스템 속성 매핑에 따라 선택한 속성에 포함됩니다. 이 프로세스는 Azure Portal을 통해 C# 또는 Python을 사용하여 프로그래밍 방식으로 관리하거나 Azure Resource Manager 템플릿을 사용하여 관리할 수 있습니다.

Azure Data Explorer의 데이터 수집에 대한 일반적인 정보는 Azure Data Explorer 데이터 수집 개요를 참조하세요.

데이터 형식

데이터는 EventData 개체 형식으로 Event Hub 엔드포인트에서 읽습니다.
지원되는 형식을 참조하세요.

참고

IoT Hub는 .raw 형식을 지원하지 않습니다.
지원되는 압축을 참조하세요.

수집 속성

수집 프로세스는 수집 속성을 통해 데이터를 라우팅할 위치와 처리 방법을 알게 됩니다. EventData.Properties를 사용하여 이벤트의 수집 속성을 지정할 수 있습니다. 다음 속성을 설정할 수 있습니다.

속성	Description
데이터베이스	대상 데이터베이스의 이름(대/소문자 구분)입니다. 데이터 연결이 만들어진 데이터베이스(기본 데이터베이스)와 다른 데이터베이스로 데이터를 보내려는 경우 이 속성을 사용할 수 있습니다. 데이터를 여러 데이터베이스로 라우팅하려면 먼저 연결을 다중 데이터베이스 연결로 설정해야 합니다. 자세한 내용은 이벤트 라우팅을 참조하세요.
테이블	기존 대상 테이블의 이름(대/소문자 구분)입니다. `Data Connection` 창에 설정된 `Table`을 재정의합니다.
형식	데이터 형식. `Data Connection` 창에 설정된 `Data format`을 재정의합니다.
IngestionMappingReference	사용할 기존 수집 매핑의 이름입니다. `Data Connection` 창에 설정된 `Column mapping`을 재정의합니다.
Encoding	데이터 인코딩, 기본값은 UTF8입니다. .NET 지원 인코딩 중 하나일 수 있습니다.

참고

데이터 연결을 만든 후에 큐에 넣은 이벤트만 수집됩니다.

이벤트 라우팅

클러스터에 대한 데이터 연결을 만들 때 수집된 데이터를 보낼 위치에 대한 라우팅을 지정합니다. 기본 라우팅은 대상 데이터베이스와 연결된 연결 문자열에 지정된 대상 테이블로 라우팅하는 것입니다. 데이터의 기본 라우팅을 정적 라우팅이라고도 합니다. 이벤트 데이터 속성을 사용하여 데이터에 대한 대체 라우팅을 지정할 수 있습니다.

대체 데이터베이스로 이벤트 데이터 라우팅

대체 데이터베이스로 데이터 라우팅은 기본적으로 꺼져 있습니다. 데이터를 다른 데이터베이스로 보내려면 먼저 연결을 다중 데이터베이스 연결로 설정해야 합니다. Azure Portal에서 이 작업을 수행하는 방법의 예는 다중 데이터베이스 라우팅 켜기를 참조 하세요. 데이터베이스 라우팅을 허용하는 데 사용되는 사용자, 그룹, 서비스 주체 또는 관리 ID에는 적어도 클러스터에 대한 기여자 역할 및 쓰기 권한이 있어야 합니다.

대체 데이터베이스를 지정하려면 데이터베이스 수집 속성을 설정합니다.

Warning

연결을 다중 데이터베이스 데이터 연결로 설정하지 않고 대체 데이터베이스를 지정하면 수집이 실패합니다.

다중 데이터베이스 라우팅 켜기

대체 대상 데이터베이스를 설정하려면 먼저 데이터를 여러 데이터베이스로 라우팅하도록 허용해야 합니다. 다음 단계를 사용하여 데이터를 대체 데이터베이스로 라우팅할 수 있습니다.

Azure Portal에서 클러스터로 이동합니다.
데이터베이스>데이터 연결을 선택합니다.
데이터 연결을 만들거나 편집하고 데이터 연결 창의 데이터 라우팅 설정에서 다른 데이터베이스로 데이터 라우팅 허용(다중 데이터베이스 데이터 연결) 옵션을 켭니다.

대체 테이블로 이벤트 데이터 라우팅

이벤트 속성을 사용하여 각 이벤트에 대한 대상 테이블 속성을 지정할 수도 있습니다. 연결은 이벤트의 정적 속성을 재정의하여 EventData.Properties에 지정된 대로 데이터를 동적으로 라우팅합니다. 대체 테이블을 지정하려면 테이블 수집 속성을 설정합니다.

참고 항목

내 데이터에 라우팅 정보가 포함됨을 선택한 경우 이벤트 속성의 일부로 필요한 라우팅 정보를 제공해야 합니다.

이벤트 시스템 속성 매핑

시스템 속성은 이벤트가 수신될 때 IoT Hub 서비스에서 설정한 속성을 저장하는 데 사용되는 컬렉션입니다. Azure Data Explorer IoT Hub 연결은 테이블의 데이터 랜딩에서 선택한 속성을 포함합니다.

참고

csv 매핑의 경우 속성은 아래 테이블에 나열된 순서대로 레코드 시작 부분에 추가됩니다. json 매핑의 경우 속성은 다음 테이블의 속성 이름에 따라 추가됩니다.

시스템 속성

IoT Hub는 디바이스-클라우드 IoT Hub 메시지에 대해 다음 시스템 속성을 노출합니다.

속성	Description
message-id	사용자가 설정할 수 있는 메시지에 대한 식별자는 요청-회신 패턴에 사용됩니다. 형식: ASCII 7 비트 영숫자 문자 + `{'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}`의 대/소문자 구분 문자열(최대 128자 길이)입니다.
iothub-enqueuedtime	IoT Hub에서 디바이스-클라우드 메시지를 수신한 날짜 및 시간입니다.
user-id	메시지의 원본을 지정하는 데 사용되는 ID입니다. IoT Hub에서 메시지가 생성되면 이 값은 `{iot hub name}`으로 설정됩니다.
iothub-connection-device-id	IoT Hub에서 디바이스-클라우드 메시지에 설정하는 ID입니다. 메시지를 보낸 디바이스의 deviceId를 포함합니다.
iothub-connection-module-id	IoT Hub에서 디바이스-클라우드 메시지에 설정하는 ID입니다. 메시지를 보낸 디바이스의 moduleId를 포함합니다.
iothub-connection-auth-generation-id	IoT Hub에서 디바이스-클라우드 메시지에 설정하는 ID입니다. 메시지를 보낸 디바이스의 connectionDeviceGenerationId(디바이스 ID 속성당)를 포함합니다.
iothub-connection-auth-method	IoT Hub에서 디바이스-클라우드 메시지에 설정하는 인증 방법입니다. 이 속성에는 메시지를 보내는 디바이스를 인증하는 데 사용되는 인증 방법에 대한 정보가 포함됩니다.
iothub-app-iothub-creation-time-utc	일괄 처리로 데이터를 보내는 경우 디바이스에서 이벤트 생성 시간을 보낼 수 있습니다.
iothub-creation-time-utc	한 번에 하나의 메시지를 보내는 경우 디바이스에서 이벤트 생성 시간을 보낼 수 있습니다.
dt-dataschema	이 값은 디바이스-클라우드 메시지의 IoT 허브에 의해 설정됩니다. 디바이스 연결에 설정된 디바이스 모델 ID 세트를 포함합니다.
dt-subject	디바이스-클라우드 메시지를 전송하는 구성 요소의 이름입니다.

테이블의 데이터 원본 섹션에서 이벤트 시스템 속성을 선택한 경우 테이블 스키마 및 매핑에 속성을 포함해야 합니다.

스키마 매핑 예제

테이블 스키마 매핑 예제

데이터에 세 개의 열(Timespan, Metric, Value)이 포함되고 포함된 속성이 iothub-connection-device-id와 sequence-number인 경우 다음 명령을 사용하여 테이블 스키마를 만들거나 변경합니다.

    .create-merge table TestTable (TimeStamp: datetime, Metric: string, Value: int, IotHubDeviceId:long, IotHubSequenceNumber:long)

CSV 매핑 예제

다음 명령을 실행하여 레코드의 시작 부분에 데이터를 추가합니다. 서수 값을 기록해 둡니다.

    .create table TestTable ingestion csv mapping "CsvMapping1"
    '['
    '   { "column" : "TimeStamp", "Properties":{"Ordinal":"2"}},'
    '   { "column" : "Metric", "Properties":{"Ordinal":"3"}},'
    '   { "column" : "Value", "Properties":{"Ordinal":"4"}},'
    '   { "column" : "IotHubDeviceId", "Properties":{"Ordinal":"0"}},'
    '   { "column" : "IotHubSequenceNumber", "Properties":{"Ordinal":"1"}}'
    ']'

JSON 매핑 예제

시스템 속성 매핑을 사용하여 데이터를 추가합니다. 다음 명령을 실행합니다.

    .create table TestTable ingestion json mapping "JsonMapping1"
    '['
    '    { "column" : "TimeStamp", "Properties":{"Path":"$.timestamp"}},'
    '    { "column" : "Metric", "Properties":{"Path":"$.metric"}},'
    '    { "column" : "Value", "Properties":{"Path":"$.metric_value"}},'
    '    { "column" : "IotHubDeviceId", "Properties":{"Path":"$.iothub-connection-device-id"}},'
    '    { "column" : "IotHubSequenceNumber", "Properties":{"Path":"$.sequence-number"}}'
    ']'

이벤트 사용자 속성 매핑

사용자 속성을 사용하여 IoT Hub 이벤트 페이로드를 보강하는 것은 지원되지 않습니다. 이벤트 본문 업스트림에 사용자 속성을 포함하는 것이 좋습니다.

IoT Hub 연결

참고

최상의 성능을 위해 Azure Data Explorer 클러스터와 동일한 지역에 모든 리소스를 만듭니다.

IoT Hub 만들기

IoT 허브를 만듭니다(아직 없는 경우). IoT Hub에 대한 연결은 Azure Portal을 통해 C# 또는 Python을 사용하여 프로그래밍 방식으로 관리하거나 Azure Resource Manager 템플릿을 사용하여 관리할 수 있습니다.

참고

device-to-cloud partitions 수는 변경할 수 없으므로 파티션 수를 설정할 때 장기적인 규모를 고려해야 합니다.
소비자 그룹은 소비자별로 고유해야 합니다. Azure Data Explorer 연결 전용 소비자 그룹을 만듭니다. Azure Portal에서 리소스를 찾고 Built-in endpoints로 이동하여 새 소비자 그룹을 추가합니다.
데이터 연결은 IoT Hub Built-in endpoint를 사용합니다. 다른 Message routing endpoint를 구성하는 경우 해당 엔드포인트에 대한 경로가 만들어지지 않는 한 메시지는 Built-in endpoint로의 흐름을 중지합니다. 새 경로가 추가된 경우에도 메시지가 기본 제공 엔드포인트로 계속 흐르도록 하려면 events 엔드포인트에 대한 경로를 구성합니다. 자세한 내용은 IoT Hub 메시지 라우팅 문제 해결을 참조하세요.

이벤트 전송

디바이스를 시뮬레이션하고 데이터를 생성하는 샘플 프로젝트를 참조하세요.

다음 단계

IoT Hub 데이터 연결 만들기

다음을 통해 공유