자습서: IoT Hub 메시지 라우팅을 사용하여 디바이스 데이터를 Azure Storage로 보내기

Azure IoT Hub에서 메시지 라우팅을 사용하여 Blob Storage, Service Bus 큐, Service Bus 토픽 및 Event Hubs와 같은 IoT 디바이스 Azure 서비스에서 원격 분석 데이터를 보냅니다. 모든 IoT Hub에는 Event Hubs와 호환되는 기본 제공 엔드포인트가 있습니다. 라우팅 쿼리를 정의하여 사용자 지정 엔드포인트를 만들고 다른 Azure 서비스로 메시지를 라우팅할 수도 있습니다. IoT Hub에 도착하는 각 메시지는 라우팅 쿼리가 일치하는 모든 엔드포인트로 라우팅됩니다. 메시지는 정의된 모든 라우팅 쿼리와 일치하지 않으면 기본 엔드포인트로 라우팅됩니다.

이 자습서에서는 다음 작업을 수행합니다.

• IoT Hub를 만들고 디바이스 메시지를 보냅니다.
• 스토리지 계정 만들기
• 스토리지 계정에 대한 사용자 지정 엔드포인트를 만들고 IoT Hub에서 메시지를 라우팅합니다.
• 스토리지 계정 Blob의 디바이스 메시지를 봅니다.

필수 구성 요소

• Azure 구독 Azure 구독이 아직 없는 경우 시작하기 전에 체험 계정을 만듭니다.

• Azure 구독의 IoT Hub 아직 허브가 없는 경우 IoT Hub 만들기의 단계를 따를 수 있습니다.

• 이 자습서에서는 C#용 Azure IoT SDK의 샘플 코드를 사용합니다.

  • SDK 리포지토리를 개발 머신에 다운로드하거나 복제합니다.
  • 개발 머신에 .NET Core 3.0.0 이상을 설치합니다. dotnet --version을 실행하여 버전을 확인하고 필요한 경우 .NET을 다운로드합니다.

• 방화벽에서 포트 8883이 열려 있는지 확인합니다. 이 자습서의 샘플은 포트 8883을 통해 통신하는 MQTT 프로토콜을 사용합니다. 이 포트는 일부 회사 및 교육용 네트워크 환경에서 차단될 수 있습니다. 이 문제를 해결하는 자세한 내용과 방법은 IoT Hub에 연결(MQTT)을 참조하세요.

• 필요에 따라 Azure IoT Explorer를 설치합니다. 이 도구를 사용하면 메시지가 IoT Hub에 도착할 때 메시지를 관찰할 수 있습니다. 이 문서에서는 Azure IoT Explorer를 사용합니다.

Azure Portal

Azure Portal에 대한 다른 필수 구성 요소는 없습니다.

Azure CLI

• Azure Cloud Shell에서 Bash 환경을 사용합니다. 자세한 내용은 Azure Cloud Shell의 Bash에 대한 빠른 시작을 참조하세요.

  

• CLI 참조 명령을 로컬에서 실행하려면 Azure CLI를 설치합니다. Windows 또는 macOS에서 실행 중인 경우 Docker 컨테이너에서 Azure CLI를 실행하는 것이 좋습니다. 자세한 내용은 Docker 컨테이너에서 Azure CLI를 실행하는 방법을 참조하세요.

  • 로컬 설치를 사용하는 경우 az login 명령을 사용하여 Azure CLI에 로그인합니다. 인증 프로세스를 완료하려면 터미널에 표시되는 단계를 수행합니다. 다른 로그인 옵션은 Azure CLI를 사용하여 로그인을 참조하세요.

  • 메시지가 표시되면 처음 사용할 때 Azure CLI 확장을 설치합니다. 확장에 대한 자세한 내용은 Azure CLI에서 확장 사용을 참조하세요.

  • az version을 실행하여 설치된 버전과 종속 라이브러리를 찾습니다. 최신 버전으로 업그레이드하려면 az upgrade를 실행합니다.

디바이스 등록 및 IoT Hub로 메시지 보내기

IoT 허브에 새 디바이스를 등록합니다.

Important

이 문서에서는 공유 액세스 서명(대칭 키 인증이라고도 함)을 사용하여 디바이스를 연결하는 단계를 설명합니다. 이 인증 방법은 테스트와 평가에 편리하지만, X.509 인증서를 사용하여 디바이스를 인증하는 것이 더 안전한 방식입니다. 자세한 내용은 보안 모범 사례 > 연결 보안을 참조하세요.

Azure Portal

1. Azure Portal에 로그인하고 IoT Hub로 이동합니다.

2. 메뉴의 디바이스 관리 섹션에서 디바이스를 선택합니다.

3. 디바이스 추가를 선택합니다.

   

4. 디바이스 ID를 제공하고 저장을 선택합니다.

5. 새 디바이스는 이제 디바이스 목록에 표시됩니다. 그렇지 않은 경우 페이지를 새로 고칩니다. 디바이스 ID를 선택하여 디바이스 세부 정보 페이지를 엽니다.

6. 디바이스 키 중 하나를 복사하여 저장합니다. 이 값을 사용하여 시뮬레이트된 디바이스 원격 분석 메시지를 생성하는 샘플 코드를 구성합니다.

   

Azure CLI

팁

이 자습서 전체에서 사용되는 대부분의 CLI 명령은 동일한 매개 변수를 사용합니다. 편의를 위해 필요에 따라 호출할 수 있는 지역 변수를 정의했습니다. 동일한 세션에서 모든 명령을 실행해야 합니다. 그렇지 않으면 변수를 다시 정의해야 합니다.

1. IoT Hub 및 디바이스에 대한 변수를 정의합니다.

   IOTHUB_NAME: 이 자리 표시자를 IoT Hub의 이름으로 바꿉니다.

   DEVICE_NAME: 이 자리 표시자를 이 자습서에서 디바이스에 사용할 이름으로 바꿉니다.

   hubName=IOTHUB_NAME
   deviceName=DEVICE_NAME
   

2. CLI 셸에서 az iot hub device-identity create 명령을 실행합니다. 이 명령은 디바이스 ID를 만듭니다.

   az iot hub device-identity create --device-id $deviceName --hub-name $hubName
   

3. 디바이스 ID 출력에서 따옴표로 묶지 말고 primaryKey 값을 복사한 후 저장합니다. 이 값을 사용하여 시뮬레이트된 디바이스 원격 분석 메시지를 생성하는 샘플 코드를 구성합니다.

이제 디바이스 ID와 키가 있으므로 샘플 코드를 사용하여 IoT Hub에 디바이스 원격 분석 메시지 보내기를 시작합니다.

팁

이 자습서의 Azure CLI 단계를 따르는 경우 별도의 세션에서 샘플 코드를 실행합니다. 이렇게 하면 나머지 CLI 단계를 수행하는 동안 샘플 코드가 계속 실행되도록 허용할 수 있습니다.

1. 필수 구성 요소의 일부로 이 작업을 수행하지 않은 경우 지금 GitHub에서 C# 리포지토리에 대한 Azure IoT SDK를 다운로드하거나 복제합니다.

2. SDK를 다운로드하거나 복제한 폴더에서 azure-iot-sdk-csharp\iothub\device\samples\how to guides\HubRoutingSample 폴더로 이동합니다.

3. HubRoutingSample.csproj 파일에 지정된 대로 Azure IoT C# SDK 및 필요한 종속성을 설치합니다.

   dotnet restore
   

4. 선택한 편집기에서 Parameters.cs 파일을 엽니다. 이 파일은 샘플에서 지원하는 매개 변수를 보여 줍니다. 이 문서에서는 샘플을 실행할 때 PrimaryConnectionString 매개 변수만 사용합니다. 이 파일의 코드를 살펴보세요. 변경할 필요는 없습니다.

5. 다음 명령을 사용하여 샘플 코드를 빌드하고 실행합니다.

   <myDevicePrimaryConnectionString>을 IoT 허브의 디바이스에서 기본 연결 문자열로 대체합니다.

   dotnet run --PrimaryConnectionString <myDevicePrimaryConnectionString>
   

6. 메시지가 IoT Hub로 전송될 때 출력에 인쇄되는 메시지가 표시되어야 합니다. 자습서를 진행하는 동안 이 프로그램을 실행 상태로 둡니다.

메시지를 표시하도록 IoT Explorer 구성

IoT Hub에 연결하고 기본 제공 엔드포인트에 도착한 메시지를 읽도록 IoT Explorer를 구성합니다.

먼저, IoT Hub의 연결 문자열을 검색합니다.

Azure Portal

1. Azure Portal에서 IoT Hub로 이동합니다.

2. 메뉴의 보안 설정 섹션에서 공유 액세스 정책을 선택합니다.

3. iothubowner 정책을 선택합니다.

   

4. 기본 연결 문자열을 복사합니다.

   

Azure CLI

1. az iot hub connection-string show 명령을 실행합니다.

   az iot hub connection-string show --hub-name $hubName
   

2. 따옴표로 묶지 말고 연결 문자열을 복사합니다.

이제 해당 연결 문자열을 사용하여 IoT Hub에 대한 IoT Explorer를 구성합니다.

1. 개발 머신에서 IoT Explorer를 엽니다.

2. 연결 추가를 선택합니다.

   

3. 허브의 연결 문자열을 텍스트 상자에 붙여넣습니다.

4. 저장을 선택합니다.

5. IoT Hub에 연결하면 디바이스 목록이 표시됩니다. 이 자습서에 대해 만든 디바이스 ID를 선택합니다.

6. 원격 분석을 선택합니다.

7. 디바이스가 계속 실행 중인 상태에서 시작을 선택합니다. 디바이스가 실행되고 있지 않으면 원격 분석이 표시되지 않습니다.

   

8. 디바이스에서 도착하는 메시지가 표시되고 가장 최근 항목이 맨 위에 표시됩니다.

   

   들어오는 메시지를 잠시 확인하여 일반, 스토리지 및 중요 메시지의 세 가지 유형이 표시되는지 알아봅니다. 이 항목이 표시되면 디바이스를 중지할 수 있습니다.

이러한 메시지는 모두 IoT Hub에 대한 기본 제공 엔드포인트에 도착합니다. 다음 섹션에서는 사용자 지정 엔드포인트를 만들고 메시지 속성에 따라 이러한 메시지 중 일부를 스토리지로 라우팅합니다. 이러한 메시지는 IoT Hub의 다른 경로와 일치하지 않는 경우에만 기본 제공 엔드포인트로 이동하므로 IoT Explorer에 표시되지 않습니다.

메시지 라우팅 설정

시뮬레이트된 디바이스에 의해 메시지에 연결된 속성에 따라 다양한 리소스로 메시지를 라우팅합니다. 사용자 지정 라우팅 메시지가 아닌 메시지는 기본 엔드포인트로 전송됩니다(메시지/이벤트).

이 자습서의 샘플 앱은 IoT Hub에 보내는 각 메시지에 level 속성을 할당합니다. 각 메시지에는 normal, storage 또는 critical 수준이 임의로 할당됩니다.

첫 단계에서는 데이터가 라우팅될 엔드포인트를 설정합니다. 두 번째 단계에서는 이 엔드포인트를 사용하는 메시지 경로를 설정합니다. 라우팅을 설정한 후에는 포털에서 엔드포인트와 메시지 경로를 볼 수 있습니다.

저장소 계정 만들기

Azure Storage 계정과 해당 계정 내에 컨테이너를 만들어 해당 계정으로 라우팅되는 디바이스 메시지를 저장합니다.

Azure Portal

1. Azure Portal을 열고 스토리지 계정을 검색합니다.

2. 만들기를 실행합니다.

3. 스토리지 계정에 대해 다음 값을 제공합니다.

   매개 변수	값
   구독	IoT hub를 포함하는 동일한 구독을 선택합니다.
   리소스 그룹	IoT hub가 포함된 동일한 리소스 그룹을 선택합니다.
   스토리지 계정 이름	스토리지 계정에 전역적으로 고유한 이름을 제공합니다.
   성능	기본 표준 값을 수락합니다.

   

4. 검토 + 만들기를 선택하여 다른 모든 기본값을 수락할 수 있습니다.

5. 유효성 검사가 완료되면 만들기를 선택합니다.

6. 배포가 완료되면 리소스로 이동을 선택합니다.

7. 스토리지 계정 메뉴의 데이터 스토리지 섹션에서 컨테이너를 선택합니다.

8. + 컨테이너를 선택하여 새 컨테이너를 만듭니다.

   

9. 컨테이너의 이름을 입력하고 만들기를 선택합니다.

Azure CLI

1. 스토리지 계정 및 컨테이너에 대한 변수를 정의합니다.

   GROUP_NAME: 이 자리 표시자를 IoT hub가 포함된 리소스 그룹의 이름으로 바꿉니다.

   STORAGE_NAME: 이 자리 표시자를 스토리지 계정의 이름으로 바꿉니다. 스토리지 계정 이름은 소문자여야 하며 전역적으로 고유해야 합니다.

   CONTAINER_NAME: 이 자리 표시자를 컨테이너의 이름으로 바꿉니다.

   resourceGroup=GROUP_NAME
   storageName=STORAGE_NAME
   containerName=CONTAINER_NAME
   

2. az storage account create 명령을 사용하여 표준 범용 v2 스토리지 계정을 만듭니다.

   az storage account create --name $storageName --resource-group $resourceGroup
   

3. az storage container create를 사용하여 스토리지 계정에 컨테이너를 추가합니다.

   az storage container create --auth-mode login --account-name $storageName --name $containerName
   

스토리지 계정으로 라우팅

이제 스토리지 계정에 대한 라우팅을 설정합니다. 이 섹션에서는 만든 스토리지 계정을 가리키는 새 엔드포인트를 정의합니다. 그런 다음, level 속성이 스토리지로 설정된 메시지를 필터링하고 이를 엔드포인트로 라우팅하는 경로를 만듭니다.

참고 항목

데이터는 Apache Avro(기본 형식) 또는 JSON으로 Blob Storage에 작성할 수 있습니다.

인코딩 형식은 Blob Storage 엔드포인트를 구성할 때만 설정할 수 있습니다. 이미 설정된 엔드포인트에 대해서는 형식을 변경할 수 없습니다. JSON 인코딩을 사용하는 경우에는 메시지 시스템 속성에서 contentType을 JSON으로 설정하고 contentEncoding을 UTF-8로 설정해야 합니다.

Blob Storage 엔드포인트 사용에 대한 자세한 내용은 Storage로 라우팅에 대한 지침을 참조하세요.

Important

이 문서에서는 공유 액세스 서명을 사용하여 서비스에 연결하는 단계를 설명합니다. 이 인증 방법은 테스트와 평가에 편리하지만, Microsoft Entra ID나 관리 ID를 사용하여 서비스를 인증하는 것이 더 안전한 방식입니다. 자세한 내용은 보안 모범 사례 > 클라우드 보안을 참조하세요.

Azure Portal

1. Azure Portal에서 IoT Hub로 이동합니다.

2. 허브 설정 아래의 리소스 메뉴에서 메시지 라우팅을 선택한 다음 추가를 선택합니다.

   

3. 엔드포인트 탭에서 다음 정보를 제공하여 스토리지 엔드포인트를 만듭니다.

   매개 변수	값
   엔드포인트 유형	스토리지를 선택합니다.
   엔드포인트 이름	엔드포인트에 대한 고유한 이름을 제공합니다.
   Azure Storage 컨테이너	컨테이너 선택을 선택합니다. 프롬프트에 따라 이전 섹션에서 만든 스토리지 계정 및 컨테이너를 선택합니다.
   인코딩	JSON을 선택합니다. 이 필드가 회색으로 표시되면 스토리지 계정 지역은 JSON을 지원하지 않습니다. 이 경우 기본 AVRO를 계속 사용합니다.

   

4. 나머지 매개 변수에 대한 기본값을 적용하고 만들기 + 다음을 선택합니다.

5. 경로 탭에서 다음 정보를 제공하여 만든 스토리지 엔드포인트를 가리키는 경로를 만듭니다.

   매개 변수	값
   이름	경로의 이름을 만듭니다.
   데이터 원본	드롭다운 목록에서 디바이스 원격 분석 메시지가 선택되어 있는지 확인합니다.
   경로 사용	이 필드가 선택되어 있는지 확인합니다.
   라우팅 쿼리	쿼리 문자열로 level="storage"을 입력합니다.

   

6. 만들기 + 보강 건너뛰기를 선택합니다.

Azure CLI

1. 엔드포인트 및 경로 명령에 필요한 변수를 구성합니다.

   ENDPOINT_NAME: 스토리지 컨테이너를 나타내는 엔드포인트의 이름을 제공합니다.

   ROUTE_NAME: 스토리지 엔드포인트에 대한 메시지를 필터링하는 경로의 이름을 제공합니다.

   endpointName=ENDPOINT_NAME
   routeName=ROUTE_NAME
   

2. az iot hub message-endpoint create 명령을 사용하여 이전 섹션에서 만든 스토리지 컨테이너를 가리키는 사용자 지정 엔드포인트를 만듭니다.

   az iot hub message-endpoint create storage-container \
     --connection-string $(az storage account show-connection-string --name $storageName --query connectionString -o tsv) \
     --endpoint-name $endpointName \
     --hub-name $hubName \
     --container $containerName \
     --resource-group $resourceGroup \
     --encoding json
   

3. az iot hub message-route create 명령을 사용하여 level=storage인 모든 메시지를 스토리지 컨테이너 엔드포인트로 전달하는 경로를 만듭니다.

   az iot hub message-route create \
     --route-name $routeName \
     --hub-name $hubName \
     --resource-group $resourceGroup \
     --source-type devicemessages \
     --endpoint-name $endpointName \
     --enabled true \
     --condition 'level="storage"'
   

라우팅된 메시지 보기

IoT Hub에 경로가 만들어지고 사용하도록 설정되면 해당 쿼리 조건을 충족하는 메시지를 스토리지 엔드포인트로 즉시 라우팅하기 시작합니다.

IoT Explorer를 사용하여 기본 제공 엔드포인트 모니터링

개발 머신의 IoT Explorer 세션으로 돌아갑니다. IoT Explorer는 IoT Hub에 대한 기본 제공 엔드포인트를 모니터링합니다. 즉, 이제 만든 사용자 지정 경로로 라우팅되지 않는 메시지만 표시됩니다.

코드를 실행하여 샘플을 다시 시작합니다. 몇 분 동안 들어오는 메시지를 확인하면 level이 normal 또는 critical로 설정된 메시지만 표시됩니다.

스토리지 컨테이너에서 메시지 보기

메시지가 스토리지 컨테이너에 도착하는지 확인합니다.

1. Azure Portal에서 스토리지 계정으로 이동합니다.

2. 메뉴의 데이터 스토리지 섹션에서 컨테이너를 선택합니다.

3. 이 자습서에 대해 만든 컨테이너를 선택합니다.

4. 이름이 IoT hub인 폴더가 있어야 합니다. .json 파일에 도착할 때까지 파일 구조를 드릴다운합니다.

   

5. JSON 파일을 선택한 다음, 다운로드를 선택하여 JSON 파일을 다운로드합니다. 파일에 level 속성이 storage로 설정된 디바이스의 메시지가 포함되어 있음을 확인합니다.

6. 샘플 실행을 중지합니다.

리소스 정리

이 자습서에 사용된 모든 Azure 리소스를 모두 제거하려면 리소스 그룹을 삭제합니다. 이렇게 하면 그룹 내에 포함된 모든 리소스가 삭제됩니다. 전체 리소스 그룹을 삭제하지 않으려면 Azure Portal을 사용하여 개별 리소스를 찾아서 삭제합니다.

다음 자습서를 계속 진행하려면 여기에서 만든 리소스를 유지하세요.

Azure Portal

1. Azure Portal에서 이 자습서의 IoT Hub 및 스토리지 계정이 포함된 리소스 그룹으로 이동합니다.
2. 리소스 그룹에 있는 모든 리소스를 검토하여 정리할 리소스를 결정합니다.
   • 모든 리소스를 삭제하려는 경우리소스 그룹 삭제를 선택합니다.
   • 특정 리소스만 삭제하려면 각 리소스 이름 옆에 있는 확인란을 사용하여 삭제할 리소스를 선택합니다. 그런 다음 삭제를 선택합니다.

Azure CLI

1. az resource list 명령을 사용하여 리소스 그룹의 모든 리소스를 봅니다.

   az resource list --resource-group $resourceGroup --output table
   

2. 리소스 그룹에 있는 모든 리소스를 검토하여 정리할 리소스를 결정합니다.

   • 모든 리소스를 삭제하려면 az group delete 명령을 사용합니다.

     az group delete --name $resourceGroup
     

   • 특정 리소스만 삭제하려면 az resource delete 명령을 사용합니다. 예시:

     az resource delete --resource-group $resourceGroup --name $storageName
     

다음 단계

이 자습서에서는 Azure 리소스에 대한 사용자 지정 엔드포인트를 만든 다음, 해당 엔드포인트에 디바이스 메시지를 보내는 경로를 만드는 방법을 알아보았습니다. 다음 자습서를 계속 진행하여 다운스트림 처리를 간소화하는 데 사용할 수 있는 추가 데이터로 메시지를 보강하는 방법을 알아봅니다.

Azure IoT Hub 메시지 보강 사용