Event Hubs로 IoT 데이터 내보내기

이 문서에서는 데이터를 Event Hubs에 보내도록 데이터 내보내기를 구성하는 방법을 설명합니다.

이 기능을 사용하여 IoT Central 애플리케이션에서 필터링되고 보강된 IoT 데이터를 지속적으로 내보낼 수 있습니다. 데이터 내보내기는 웜 경로 인사이트, 분석 및 스토리지를 위해 변경 내용을 클라우드 솔루션의 다른 부분에 거의 실시간으로 푸시합니다.

예를 들어 다음을 수행할 수 있습니다.

• 원격 분석, 속성 변경, 디바이스 연결, 디바이스 수명 주기, 디바이스 템플릿 수명 주기 및 감사 로그 데이터를 JSON 형식으로 거의 실시간으로 지속적으로 내보냅니다.
• 데이터 스트림을 필터링하여 사용자 지정 조건과 일치하는 데이터를 내보냅니다.
• 데이터 스트림을 디바이스의 사용자 지정 값 및 속성 값으로 보강합니다.
• 데이터 스트림을 변환하여 해당 셰이프 및 콘텐츠를 수정합니다.

팁

데이터 내보내기를 켜면 그 시점 이후의 데이터만 가져옵니다. 더 많은 기록 데이터를 유지하려면 데이터 내보내기를 초기에 켜세요. 데이터 내보내기가 꺼진 시점부터 데이터를 수동으로 내보내려면 IoT Central REST API를 사용하여 디바이스를 쿼리하는 방법을 참조하세요.

참고 항목

경우에 따라 메시지를 내보내는 데 최대 60초가 걸릴 수 있습니다. 이 시간은 IoT Central이 기본 IoT 허브에서 메시지를 받는 시점부터 메시지가 대상 엔드포인트로 전달되는 시점까지 측정됩니다.

필수 조건

데이터 내보내기 기능을 사용하려면 데이터 내보내기 권한이 있어야 합니다.

Event Hubs 내보내기 대상 설정

IoT Central은 데이터를 거의 실시간으로 내보냅니다. 데이터는 메시지 본문에 있으며 UTF-8로 인코딩된 JSON 형식입니다.

메시지의 주석 또는 시스템 속성 모음에는 메시지 본문의 해당 필드와 동일한 값이 있는 iotcentral-device-id, iotcentral-application-id, iotcentral-message-source 및 iotcentral-message-type 필드가 포함됩니다.

연결 옵션

Event Hubs 대상을 사용하면 연결 문자열 또는 관리 ID를 사용하여 연결을 구성할 수 있습니다.

관리 ID는 다음과 같은 이유로 더 안전합니다.

• IoT Central 애플리케이션의 연결 문자열에 리소스에 대한 자격 증명을 저장하지 않습니다.
• 자격 증명은 IoT Central 애플리케이션의 수명에 자동으로 연결됩니다.
• 관리 ID는 보안 키를 정기적으로 자동 회전합니다.

IoT Central은 현재 시스템이 할당한 관리 ID를 사용합니다.

관리 ID를 구성할 때 구성에는 범위 및 역할이 포함됩니다.

• 범위는 관리 ID를 사용할 수 있는 위치를 정의합니다. 예를 들어, Azure 리소스 그룹을 범위로 사용할 수 있습니다. 이 경우 IoT Central 애플리케이션과 대상이 모두 동일한 리소스 그룹에 있어야 합니다.
• 역할은 대상 서비스에서 IoT Central 애플리케이션에 부여되는 권한을 정의합니다. 예를 들어, IoT Central 애플리케이션이 데이터를 Event Hubs로 보내려면 관리 ID에 Azure Event Hubs 데이터 보낸 사람 역할 할당이 필요합니다.

다음 비디오에서는 시스템이 할당한 관리 ID에 대한 자세한 정보를 제공합니다.

주의

Blob Storage로 내보내려면 비디오에서와 같이 스토리지 계정 기여자를 사용하지 마세요. 대신 Storage Blob 데이터 기여자 역할을 사용합니다.

Event Hubs 대상 만들기

관리 ID

이 문서에서는 Azure CLI를 사용하여 관리 ID를 만드는 방법을 보여 줍니다. 또한 Azure Portal을 사용하여 관리 ID를 만들 수도 있습니다.

내보낼 기존 Event Hubs 네임스페이스가 없는 경우 Azure Cloud Shell bash 환경에서 다음 스크립트를 실행합니다. 이 스크립트는 리소스 그룹, Event Hubs 네임스페이스 및 이벤트 허브를 만듭니다. 그런 다음, 스크립트에서 관리 ID를 IoT Central 애플리케이션에 사용하도록 설정하고, 이벤트 허브에 액세스하는 데 필요한 역할을 할당합니다.

# Replace the Event Hubs namespace name with your own unique value
EHNS=your-event-hubs-namespace-$RANDOM

# Replace the IoT Central app name with the name of your
# IoT Central application.
CA=your-iot-central-app

EH=exportdata
RG=centralexportresources
LOCATION=eastus

RGID=$(az group create -n $RG --location $LOCATION --query "id" --output tsv)
az eventhubs namespace create --name $EHNS --resource-group $RG -l $LOCATION
az eventhubs eventhub create --name $EH --resource-group $RG --namespace-name $EHNS

# This assumes your IoT Central application is in the 
# default `IOTC` resource group.
az iot central app identity assign --name $CA --resource-group IOTC --system-assigned
PI=$(az iot central app identity show --name $CA --resource-group IOTC --query "principalId" --output tsv)

az role assignment create --assignee $PI --role "Azure Event Hubs Data Sender" --scope $RGID

az role assignment list --assignee $PI --all -o table

echo "Host name: $EHNS.servicebus.windows.net"
echo "Event Hub: $EH"

이벤트 허브를 더 안전하게 보호하고 관리 ID가 있는 신뢰할 수 있는 서비스에서만 액세스하도록 허용하려면 Azure Virtual Network에서 안전한 대상으로 데이터 내보내기를 참조하세요.

IoT Central의 데이터 내보내기 페이지에서 Event Hubs 대상을 만들려면 다음을 수행합니다.

1. + 새 대상을 선택합니다.

2. Azure Event Hubs를 대상 유형으로 입력합니다.

3. 권한 부여 유형으로 시스템이 할당한 관리 ID를 선택합니다.

4. Event Hubs 리소스의 호스트 이름을 입력합니다. 그런 다음, 대/소문자를 구분하는 이벤트 허브 이름을 입력합니다. 호스트 이름은 contoso-waste.servicebus.windows.net과 같습니다.

5. 저장을 선택합니다.

대상 서비스에 도착하는 데이터가 표시되지 않으면 Azure IoT Central 애플리케이션에서 데이터 내보내기 관련 문제 해결을 참조하세요.

연결 문자열

내보낼 기존 Event Hubs 네임스페이스가 없는 경우 Azure Cloud Shell bash 환경에서 다음 스크립트를 실행합니다. 이 스크립트는 리소스 그룹, Event Hubs 네임스페이스 및 이벤트 허브를 만듭니다. 그런 다음, IoT Central에서 데이터 내보내기를 구성할 때 사용할 연결 문자열을 출력합니다.

# Replace the Event Hubs namespace name with your own unique value
EHNS=your-event-hubs-namespace-$RANDOM
EH=exportdata
RG=centralexportresources
LOCATION=eastus

az group create -n $RG --location $LOCATION
az eventhubs namespace create --name $EHNS --resource-group $RG -l $LOCATION
az eventhubs eventhub create --name $EH --resource-group $RG --namespace-name $EHNS
az eventhubs eventhub authorization-rule create --eventhub-name $EH --resource-group $RG --namespace-name $EHNS --name SendRule --rights Send

CS=$(az eventhubs eventhub authorization-rule keys list --eventhub-name $EH --resource-group $RG --namespace-name $EHNS --name SendRule --query "primaryConnectionString" -o tsv)

echo "Event hub connection string: $CS"

IoT Central의 데이터 내보내기 페이지에서 Event Hubs 대상을 만들려면 다음을 수행합니다.

1. + 새 대상을 선택합니다.

2. Azure Event Hubs를 대상 유형으로 입력합니다.

3. 권한 부여 유형으로 연결 문자열을 선택합니다.

4. Event Hubs 리소스에 대한 연결 문자열을 붙여넣고, 필요한 경우 대/소문자를 구분하는 이벤트 허브 이름을 입력합니다.

5. 저장을 선택합니다.

데이터 내보내기 설정

이제 데이터를 내보낼 대상이 있으므로 IoT Central 애플리케이션에서 데이터 내보내기를 설정합니다.

1. IoT Central 애플리케이션에 로그인합니다.

2. 왼쪽 창에서 데이터 내보내기를 선택합니다.

   팁

   왼쪽 창에 데이터 내보내기가 표시되지 않으면 앱에서 데이터 내보내기를 구성할 수 있는 권한이 없는 것입니다. 관리자에게 데이터 내보내기를 설정하도록 요청합니다.

3. + 새 내보내기를 선택합니다.

4. 새 내보내기의 표시 이름을 입력하고, 데이터 내보내기가 사용인지 확인합니다.

5. 내보낼 데이터 형식을 선택합니다. 다음 표에는 지원되는 데이터 내보내기 형식이 나와 있습니다.

   데이터 형식	설명	데이터 형식
   원격	디바이스에서 원격 분석 메시지를 거의 실시간으로 내보냅니다. 내보낸 각 메시지에는 정규화된 원래 디바이스 메시지의 전체 내용이 포함됩니다.	원격 분석 메시지 형식
   속성 변경	디바이스 및 클라우드 속성에 대한 변경 내용을 거의 실시간으로 내보냅니다. 읽기 전용 디바이스 속성의 경우 reported 값의 변경 내용을 내보냅니다. 읽기-쓰기 속성의 경우 reported 값과 desired 값을 모두 내보냅니다.	속성 변경 메시지 형식
   디바이스 연결	디바이스 연결 및 연결 끊김 이벤트를 내 보냅니다.	디바이스 연결 메시지 형식
   디바이스 수명 주기	디바이스 등록, 삭제, 프로비저닝, 사용, 사용 안 함, displayNameChanged 및 deviceTemplateChanged 이벤트를 내보냅니다.	디바이스 수명 주기 변경 메시지 형식
   디바이스 템플릿 수명 주기	만들기, 업데이트 및 삭제를 포함하여 게시된 디바이스 템플릿 변경 내용을 내보냅니다.	디바이스 템플릿 수명 주기 변경 메시지 형식
   감사 로그	애플리케이션의 엔터티에 대한 사용자가 시작한 업데이트의 로그입니다. 자세한 내용은 감사 로그를 사용하여 IoT Central 애플리케이션에서 작업 추적을 참조하세요.	감사 로그 메시지 형식

6. 필요에 따라 필터를 추가하여 내보내는 데이터의 양을 줄입니다. 각 데이터 내보내기 형식에 사용할 수 있는 다양한 유형의 필터가 있습니다.

   데이터 형식	사용 가능한 필터
   원격	디바이스 이름, 디바이스 ID, 디바이스 템플릿 및 디바이스가 시뮬레이션되었는지 여부 필터링 필터 조건과 일치하는 원격 분석만 포함하는 필터 스트림 필터 조건과 일치하는 속성이 있는 디바이스의 원격 분석만 포함하는 필터 스트림 필터 조건을 충족하는 메시지 속성이 있는 원격 분석만 포함하도록 스트림을 필터링합니다. 메시지 속성(애플리케이션 속성이라고도 함)은 각 원격 분석 메시지의 키-값 쌍 모음에 전송됩니다. 메시지 속성 필터를 만들려면 찾고 있는 메시지 속성 키를 입력하고 조건을 지정합니다. 지정된 필터 조건과 일치하는 속성이 있는 원격 분석 메시지만 내보냅니다. IoT Hub 문서에서 애플리케이션 속성에 대해 자세히 알아보세요.
   속성 변경	디바이스 이름, 디바이스 ID, 디바이스 템플릿 및 디바이스가 시뮬레이션되었는지 여부 필터링 필터 조건과 일치하는 속성 변경만 포함하는 필터 스트림
   디바이스 연결	디바이스 이름, 디바이스 ID, 디바이스 템플릿, 조직 및 디바이스가 시뮬레이션되는지 여부를 기준으로 필터링합니다. 필터 조건과 일치하는 속성이 있는 디바이스의 변경만 포함하는 필터 스트림
   디바이스 수명 주기	디바이스 이름, 디바이스 ID, 디바이스 템플릿 및 디바이스가 프로비저닝, 사용 또는 시뮬레이션되었는지 여부 필터링 필터 조건과 일치하는 속성이 있는 디바이스의 변경만 포함하는 필터 스트림
   디바이스 템플릿 수명 주기	디바이스 템플릿 기준 필터
   감사 로그	해당 없음

7. 필요에 따라 추가 키-값 쌍 메타데이터를 사용하여 내보낸 메시지를 보강합니다. 원격 분석, 속성 변경, 디바이스 연결 및 디바이스 수명 주기 데이터 내보내기 유형에 대해 다음과 같은 보강을 사용할 수 있습니다.

   • 사용자 지정 문자열: 각 메시지에 사용자 지정 정적 문자열을 추가합니다. 아무 키나 입력하고 문자열 값을 입력합니다.
   • 각 메시지에 추가되는 속성:
     • 디바이스 이름, 디바이스 템플릿 이름, 사용, 조직, 프로비저닝됨 및 시뮬레이션됨과 같은 디바이스 메타데이터
     • 현재 디바이스는 각 메시지에 속성 또는 클라우드 속성 값을 보고했습니다. 내보낸 메시지가 지정된 속성이 없는 디바이스에서 제공된 경우 내보낸 메시지에서 보강을 받지 않습니다.

내보내기 대상을 다음과 같이 구성합니다.

1. + 대상을 선택하여 이미 만든 대상을 추가하거나 새 대상 만들기를 선택합니다.

2. 데이터를 내보내기 전에 변환하려면 + 변환을 선택합니다. 자세한 내용은 내보내기를 위해 IoT Central 애플리케이션 내의 데이터 변환을 참조하세요.

3. + 대상을 선택하여 최대 5개의 대상을 단일 내보내기에 추가합니다.

4. 내보내기 설정이 완료되면 저장을 선택합니다. 몇 분 후 대상에 데이터가 표시됩니다.

내보내기 모니터링

IoT Central에서 데이터 내보내기 페이지를 사용하면 내보내기 상태를 확인할 수 있습니다. 또한 Azure Monitor를 사용하여 내보내는 데이터의 양과 내보내기 오류를 확인할 수 있습니다. REST API, PowerShell의 쿼리 또는 Azure CLI를 사용하여 Azure Portal의 차트에서 내보내기 및 디바이스 상태 메트릭에 액세스할 수 있습니다. 현재 Azure Monitor에서 모니터링할 수 있는 데이터 내보내기 메트릭은 다음과 같습니다.

• 필터를 적용하기 전에 내보기 위해 들어오는 메시지의 수
• 필터를 통과하는 메시지의 수
• 대상으로 성공적으로 내보낸 메시지의 수
• 발견된 오류 수입니다.

자세한 내용은 애플리케이션 상태 모니터링을 참조하세요.

데이터 형식

다음 섹션에서는 내보낸 데이터의 형식에 대해 설명합니다.

원격 분석 형식

내보낸 각 메시지에는 디바이스에서 메시지 본문에 보낸 전체 메시지의 정규화된 형식이 포함됩니다. 메시지는 JSON 형식이며 UTF-8로 인코딩됩니다. 각 메시지에 포함되는 정보는 다음과 같습니다.

• applicationId: IoT Central 애플리케이션의 ID
• messageSource: 메시지의 원본(telemetry)
• deviceId: 원격 분석 메시지를 보낸 디바이스의 ID
• schema: 페이로드 스키마의 이름 및 버전
• templateId: 디바이스에 할당된 디바이스 템플릿의 ID
• enqueuedTime: IoT Central에서 이 메시지를 받은 시간
• enrichments: 내보내기에 설정된 모든 보강
• module: 이 메시지를 보낸 IoT Edge 모듈 이 필드는 메시지가 IoT Edge 모듈에서 온 경우에만 나타납니다.
• component: 이 메시지를 보낸 구성 요소 이 필드는 메시지에 전송된 기능이 디바이스 템플릿의 구성 요소로 모델링된 경우에만 나타납니다.
• messageProperties: 디바이스에서 메시지와 함께 보낸 기타 속성 이러한 속성은 애플리케이션 속성이라고도 합니다. IoT Hub 문서에서 자세히 알아보세요.

메시지 속성

원격 분석 메시지에는 메타데이터 및 원격 분석 페이로드에 대한 속성이 있습니다. 이전 코드 조각에서는 deviceId 및 enqueuedTime과 같은 시스템 메시지의 예제를 보여 줍니다. 시스템 메시지 속성에 대한 자세한 내용은 D2C IoT Hub 메시지의 시스템 속성을 참조하세요.

사용자 지정 메타데이터를 원격 분석 메시지에 추가해야 하는 경우 속성을 원격 분석 메시지에 추가할 수 있습니다. 예를 들어 디바이스에서 메시지를 만들 때 타임스탬프를 추가해야 합니다.

다음 코드 조각에서는 디바이스에서 iothub-creation-time-utc 속성을 만들 때 이 속성을 메시지에 추가하는 방법을 보여 줍니다.

Important

이 타임스탬프의 형식은 표준 시간대 정보가 없는 UTC여야 합니다. 예를 들어 2021-04-21T11:30:16Z는 유효하고 2021-04-21T11:30:16-07:00은 잘못된 것입니다.

JavaScript

async function sendTelemetry(deviceClient, index) {
  console.log('Sending telemetry message %d...', index);
  const msg = new Message(
    JSON.stringify(
      deviceTemperatureSensor.updateSensor().getCurrentTemperatureObject()
    )
  );
  msg.properties.add("iothub-creation-time-utc", new Date().toISOString());
  msg.contentType = 'application/json';
  msg.contentEncoding = 'utf-8';
  await deviceClient.sendEvent(msg);
}

Java

private static void sendTemperatureTelemetry() {
  String telemetryName = "temperature";
  String telemetryPayload = String.format("{\"%s\": %f}", telemetryName, temperature);

  Message message = new Message(telemetryPayload);
  message.setContentEncoding(StandardCharsets.UTF_8.name());
  message.setContentTypeFinal("application/json");
  message.setProperty("iothub-creation-time-utc", Instant.now().toString());

  deviceClient.sendEventAsync(message, new MessageIotHubEventCallback(), message);
  log.debug("My Telemetry: Sent - {\"{}\": {}°C} with message Id {}.", telemetryName, temperature, message.getMessageId());
  temperatureReadings.put(new Date(), temperature);
}

C#

private async Task SendTemperatureTelemetryAsync()
{
  const string telemetryName = "temperature";

  string telemetryPayload = $"{{ \"{telemetryName}\": {_temperature} }}";
  using var message = new Message(Encoding.UTF8.GetBytes(telemetryPayload))
  {
      ContentEncoding = "utf-8",
      ContentType = "application/json",
  };
  message.Properties.Add("iothub-creation-time-utc", DateTime.UtcNow.ToString("yyyy-MM-ddTHH:mm:ssZ"));
  await _deviceClient.SendEventAsync(message);
  _logger.LogDebug($"Telemetry: Sent - {{ \"{telemetryName}\": {_temperature}°C }}.");
}

Python

async def send_telemetry_from_thermostat(device_client, telemetry_msg):
    msg = Message(json.dumps(telemetry_msg))
    msg.custom_properties["iothub-creation-time-utc"] = datetime.now(timezone.utc).isoformat()
    msg.content_encoding = "utf-8"
    msg.content_type = "application/json"
    print("Sent message")
    await device_client.send_message(msg)

속성 변경 형식

각 메시지 또는 레코드는 디바이스 및 클라우드 속성에 대한 변경 내용을 나타냅니다. 내보낸 메시지에 포함되는 정보는 다음과 같습니다.

• applicationId: IoT Central 애플리케이션의 ID
• messageSource: 메시지의 원본(properties)
• messageType: cloudPropertyChange, devicePropertyDesiredChange 또는 devicePropertyReportedChange
• deviceId: 원격 분석 메시지를 보낸 디바이스의 ID
• schema: 페이로드 스키마의 이름 및 버전
• enqueuedTime: IoT Central에서 이 변경 사항을 감지한 시간
• templateId: 디바이스에 할당된 디바이스 템플릿의 ID
• properties: 변경된 속성 및 값의 이름을 포함하여 변경된 속성의 배열입니다. 속성이 구성 요소 또는 IoT Edge 모듈 내에서 모델링되는 경우 구성 요소 및 모듈 정보가 포함됩니다.
• enrichments: 내보내기에 설정된 모든 보강

디바이스 연결 변경 형식

각 메시지 또는 레코드는 단일 디바이스의 연결 이벤트를 나타냅니다. 내보낸 메시지에 포함되는 정보는 다음과 같습니다.

• applicationId: IoT Central 애플리케이션의 ID
• messageSource: 메시지의 원본(deviceConnectivity)
• messageType: connected 또는 disconnected
• deviceId: 변경된 디바이스의 ID
• schema: 페이로드 스키마의 이름 및 버전
• templateId: 디바이스에 할당된 디바이스 템플릿의 ID
• enqueuedTime: IoT Central에서 이 변경이 발생한 시간
• enrichments: 내보내기에 설정된 모든 보강

디바이스 수명 주기 변경 형식

각 메시지 또는 레코드는 단일 디바이스에 대한 변경 내용을 나타냅니다. 내보낸 메시지에 포함되는 정보는 다음과 같습니다.

• applicationId: IoT Central 애플리케이션의 ID
• messageSource: 메시지의 원본(deviceLifecycle)
• messageType: 발생한 변경 유형. registered, deleted, provisioned, enabled, disabled, displayNameChanged 및 deviceTemplateChanged 중 하나입니다.
• deviceId: 변경된 디바이스의 ID
• schema: 페이로드 스키마의 이름 및 버전
• templateId: 디바이스에 할당된 디바이스 템플릿의 ID
• enqueuedTime: IoT Central에서 이 변경이 발생한 시간
• enrichments: 내보내기에 설정된 모든 보강

디바이스 템플릿 수명 주기 변경 형식

각 메시지 또는 레코드는 게시된 단일 디바이스 템플릿에 대한 단일 변경 내용을 나타냅니다. 내보낸 메시지에 포함되는 정보는 다음과 같습니다.

• applicationId: IoT Central 애플리케이션의 ID
• messageSource: 메시지의 원본(deviceTemplateLifecycle)
• messageType: created, updated 또는 deleted
• schema: 페이로드 스키마의 이름 및 버전
• templateId: 디바이스에 할당된 디바이스 템플릿의 ID
• enqueuedTime: IoT Central에서 이 변경이 발생한 시간
• enrichments: 내보내기에 설정된 모든 보강

감사 로그 형식

각 감사 로그 메시지는 IoT Central 애플리케이션 내의 감사 가능한 엔터티에 대한 사용자가 시작한 변경을 나타냅니다. 내보낸 메시지에 포함되는 정보는 다음과 같습니다.

• actor: 엔터티를 수정한 사용자에 대한 정보.
• applicationId: IoT Central 애플리케이션의 ID
• messageSource: 메시지의 원본(audit)
• messageType: 발생한 변경 유형. updated, created, deleted 중 하나입니다.
• updated: messageType이 updated인 경우에만 표시됩니다. 업데이트에 대한 자세한 정보를 제공합니다.
• resource: 수정된 엔터티의 세부 정보
• schema: 페이로드 스키마의 이름 및 버전
• deviceId: 변경된 디바이스의 ID
• enqueuedTime: IoT Central에서 이 변경이 발생한 시간
• enrichments: 내보내기에 설정된 모든 보강

Event Hubs의 경우 IoT Central은 새 메시지 데이터를 이벤트 허브로 거의 실시간으로 내보냅니다. 각 메시지의 사용자 속성(애플리케이션 속성이라고도 함)에는 iotcentral-device-id, iotcentral-application-id, iotcentral-message-source 및 iotcentral-message-type이 자동으로 포함됩니다.

다음 단계

이제 Event Hubs로 내보내는 방법을 알아보았으므로 제안되는 다음 단계에서는 Azure Data Explorer로 내보내기를 알아봅니다.