IoT Hub를 사용하여 디바이스에서 클라우드로 파일 업로드(.NET)

이 자습서에서는 Azure IoT .NET 디바이스와 서비스 SDK를 이용해 IoT Hub의 파일 업로드 기능을 사용하는 방법을 보여 줍니다.

디바이스에서 IoT Hub로 원격 분석 보내기 빠른 시작 및 IoT Hub를 사용하여 클라우드-디바이스 메시지 보내기 자습서는 IoT Hub의 기본적인 디바이스-클라우드 및 클라우드-디바이스 메시징 기능을 보여 줍니다. IoT Hub로 메시지 라우팅 구성 자습서에서는 디바이스-클라우드 메시지를 Microsoft Azure Blob Storage에 안정적으로 저장하는 방법에 대해 설명합니다. 그러나 일부 시나리오에서는 디바이스에서 전송하는 데이터를 IoT Hub에서 허용하는 비교적 작은 디바이스-클라우드 메시지에 쉽게 매핑할 수 없습니다. 예를 들면 다음과 같습니다.

  • 이미지가 포함된 대형 파일

  • 동영상

  • 자주 샘플링되는 진동 데이터

  • 특정 형태의 전처리된 데이터

이러한 파일은 일반적으로 Azure Data Factory 또는 Hadoop 스택과 같은 도구를 사용하여 클라우드에서 배치 방식으로 처리됩니다. 그러나 디바이스에서 파일을 업로드해야 하는 경우에도 IoT Hub의 보안 및 안정성을 사용할 수 있습니다. 이 튜토리얼에서는 그 방법에 대해 설명합니다.

이 자습서의 끝 부분에서 다음의 두 .NET 콘솔 앱을 실행합니다.

  • FileUploadSample 이 디바이스 앱은 IoT 허브에서 제공하는 SAS URI를 사용하여 스토리지에 파일을 업로드합니다. 이 앱은 필수 구성 요소에서 다운로드하는 Azure IoT C# 샘플 리포지토리에서 실행합니다.

  • ReadFileUploadNotification. 이 서비스 앱은 IoT 허브에서 파일 업로드 알림을 받습니다. 여러분은 이 앱을 만들게 됩니다.

참고

IoT Hub는 Azure IoT 디바이스 SDK를 통해 많은 디바이스 플랫폼 및 언어(C, Java, Python 및 JavaScript 포함)를 지원합니다. Azure IoT Hub에 디바이스를 연결하는 방법에 대한 단계별 지침은 Azure IoT 개발자 센터를 참조하세요.

중요

X.509 CA(인증 기관) 인증을 사용하는 디바이스의 파일 업로드 기능은 공개 미리 보기로 제공되고 있으며 미리 보기 모드를 사용하도록 설정해야 합니다. 일반적으로 X.509 지문 인증을 사용하는 디바이스에서 사용할 수 있습니다. IoT Hub를 사용하는 X.509 인증에 대해 자세히 알아보려면 지원되는 X.509 인증서를 참조하세요.

사전 요구 사항

  • 활성 Azure 계정. 계정이 없는 경우 몇 분 안에 무료 계정 을 만들 수 있습니다.

  • 이 문서에서 실행하는 샘플 애플리케이션은 C#을 사용하여 작성되었습니다. Azure IoT C# 샘플의 경우 개발 머신에 .NET Core SDK 3.1 이상이 설치되어 있는 것이 좋습니다.

    .NET에서 여러 플랫폼에 대한 .NET Core SDK를 다운로드할 수 있습니다.

    다음 명령을 사용하여 개발 머신에서 .NET Core SDK의 현재 버전을 확인할 수 있습니다.

    dotnet --version
    
  • https://github.com/Azure-Samples/azure-iot-samples-csharp/archive/main.zip에서 Azure IoT C# 샘플을 다운로드하고 ZIP 보관 파일을 추출합니다.

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

IoT Hub 만들기

이 섹션에서는 Azure Portal을 사용하여 IoT Hub를 만드는 방법에 대해 설명합니다.

  1. Azure Portal에 로그인합니다.

  2. Azure 홈페이지에서 +리소스 만들기를 클릭한 다음, Marketplace 검색 필드에 IoT Hub를 입력합니다.

  3. 검색 결과에서 IoT Hub, 만들기를 차례로 선택합니다.

  4. 기본 탭에서 다음과 같이 필드를 완성합니다.

    • 구독: 허브에 사용할 구독을 선택합니다.

    • 리소스 그룹: 리소스 그룹을 선택하거나 새로 만듭니다. 새 리소스 그룹을 만들려면 새로 만들기를 선택하고 사용하려는 이름을 입력합니다. 기존 리소스 그룹을 사용하려면 해당 기존 리소스 그룹을 선택합니다. 자세한 내용은 Azure Resource Manager 리소스 그룹 관리를 참조하세요.

    • 지역: 허브를 배치할 지역을 선택합니다. 가장 가까운 위치를 선택합니다. IoT Hub 디바이스 스트림과 같은 일부 기능은 특정 지역에서만 사용할 수 있습니다. 이러한 제한된 기능의 경우 지원되는 지역 중 하나를 선택해야 합니다.

    • IoT Hub 이름: 허브 이름을 입력합니다. 이 이름은 전역적으로 고유해야 하며 3~50자 사이의 영숫자여야 합니다. 이름에 대시('-') 문자를 포함할 수도 있습니다.

    중요

    IoT 허브는 DNS 엔드포인트로 공개적으로 검색될 수 있기 때문에 이름을 지정할 때 민감하거나 개인을 식별할 수 있는 정보는 입력하지 마십시오.

    Create a hub in the Azure portal.

  5. 완료되면 다음: 네트워킹을 선택하여 허브를 계속 만듭니다.

    디바이스에서 IoT Hub에 연결하는 데 사용할 수 있는 엔드포인트를 선택합니다. 퍼블릭 엔드포인트(모든 네트워크) 기본 설정을 선택하거나 퍼블릭 엔드포인트(선택한 IP 범위) 또는 프라이빗 엔드포인트를 선택할 수 있습니다. 이 예제의 기본 설정을 적용합니다.

    Choose the endpoints that can connect.

  6. 완료되면 다음: 관리를 선택하여 허브를 계속 만듭니다.

    Set the size and scale for a new hub using the Azure portal.

    여기서 기본 설정을 적용할 수 있습니다. 원하는 경우 다음 필드 중 하나를 수정할 수 있습니다.

    • 가격 책정 및 크기 조정 계층: 선택한 계층입니다. 원하는 기능 수와 하루에 솔루션을 통해 보내는 메시지 수에 따라 여러 계층에서 선택할 수 있습니다. 무료 계층은 테스트와 평가를 위해 제공됩니다. 허브에 500개 디바이스를 연결할 수 있으며 하루에 8,000개 메시지까지 허용합니다. 각 Azure 구독은 체험 계층에 하나의 IoT Hub를 만들 수 있습니다.

      IoT Hub 디바이스 스트림용 빠른 시작을 통해 작업하는 경우 무료 계층을 선택합니다.

    • IoT Hub 단위: 하루 단위당 허용되는 메시지의 수는 허브의 가격 책정 계층에 따라 다릅니다. 예를 들어 허브가 700,000개의 메시지 수신을 지원하려면 S1 계층 단위 2개를 선택합니다. 다른 계층 옵션에 대한 자세한 내용은 적절한 IoT Hub 계층 선택을 참조하세요.

    • Microsoft Defender for IoT: IoT및 디바이스에 추가 위협 방지 계층을 추가하려면 이 설정을 설정합니다. 무료 계층의 허브에는 이 옵션을 사용할 수 없습니다. Defender for IoT의 IoT Hub 대한 보안 권장 사항에대해 자세히 알아봅니다.

    • 고급 설정디바이스-클라우드 파티션: 이 속성은 디바이스-클라우드 메시지를 메시지의 동시 판독기 수와 연결합니다. 대부분의 허브에는 4개의 파티션만 필요합니다.

  7. 완료되면 다음: 태그를 선택하여 다음 화면으로 계속 진행합니다.

    태그는 이름/값 쌍입니다. 동일한 태그를 여러 리소스 및 리소스 그룹에 할당하여 리소스를 범주화하고 청구를 통합할 수 있습니다. 이 문서에서는 태그를 추가하지 않습니다. 자세한 내용은 태그를 사용하여 Azure 리소스 구성을 참조하세요.

    Assign tags for the hub using the Azure portal.

  8. 완료되면 다음: 검토 + 만들기를 선택하여 선택 사항을 검토합니다. 이 화면과 유사한 내용이 표시되지만 허브를 만들 때 선택한 값이 표시됩니다.

    Review information for creating the new hub.

  9. 만들기를 선택하여 새 허브의 배포를 시작합니다. 허브가 만들어지는 몇 분 동안 배포가 진행됩니다. 배포가 완료되면 리소스로 이동을 선택하여 새 허브를 엽니다.

IoT Hub에서 새 디바이스 등록

이 섹션에서는 IoT 허브의 ID 레지스트리에 디바이스 ID를 만듭니다. ID 레지스트리에 항목이 없는 경우 디바이스를 허브에 연결할 수 없습니다. 자세한 내용은 IoT Hub 개발자 가이드를 참조하세요.

  1. IoT Hub 탐색 메뉴에서 디바이스를연 다음, 디바이스 추가를 선택하여 IoT Hub에 디바이스를 추가합니다.

    Screen capture that shows how to create a device identity in the portal

  2. 디바이스 만들기에서 myDeviceId와 같은 새 디바이스의 이름을 지정하고 저장을 선택합니다. 이 작업은 IoT Hub에 대한 디바이스 ID를 만듭니다. 기본 및 보조 키가 자동으로 생성되도록 자동 생성 키를 선택된 상태로 둡니다.

    Screen capture that shows how to add a new device

    중요

    고객 지원 및 문제 해결을 위해 수집한 로그에 디바이스 ID를 표시할 수 있으므로 이름을 지정하는 동안 중요한 정보를 피해야 합니다.

  3. 디바이스를 만든 후 디바이스 창의 목록에서 디바이스를 엽니다. 기본 연결 문자열을 복사합니다. 이 연결 문자열은 디바이스 코드에서 허브와 통신하는 데 사용됩니다.

    기본적으로 키와 연결 문자열은 중요한 정보이므로 마스킹됩니다. 눈 모양 아이콘을 클릭하면 표시됩니다. 복사 단추를 사용하여 복사하도록 표시할 필요는 없습니다.

    Screen capture that shows the device connection string

참고

IoT Hub ID 레지스트리는 디바이스 ID만 저장하여 IoT Hub에 보안 액세스를 사용합니다. 보안 자격 증명으로 사용하기 위해 디바이스 ID 및 키와 개별 디바이스에 대해 액세스하지 못하도록 설정할 수 있는 사용/사용 안 함 플래그를 저장합니다. 애플리케이션이 다른 디바이스별 메타데이터를 저장해야 할 경우 애플리케이션별 스토리지를 사용해야 합니다. 자세한 내용은 IoT Hub 개발자 가이드를 참조하세요.

Azure Storage 계정을 IoT Hub에 연결

디바이스에서 파일을 업로드하려면 IoT 허브와 연결된 Azure Storage 계정 및 Azure Blob Storage 컨테이너가 있어야 합니다. 스토리지 계정 및 컨테이너를 IoT 허브와 연결하면 IoT 허브가 디바이스에서 요청될 때 SAS URI의 요소를 제공할 수 있습니다. 그런 다음, 디바이스는 이러한 요소를 사용하여 Azure Storage를 인증하고 Blob 컨테이너에 파일을 업로드하는 데 사용하는 SAS URI를 생성할 수 있습니다.

Azure Storage 계정을 IoT 허브와 연결하려면 다음을 수행합니다.

  1. 허브 설정아래에서 IoT Hub의 왼쪽 창에서 파일 업로드를 선택합니다.

    Screen capture showing select file upload settings from the portal.

  2. 파일 업로드 창에서 Azure Storage 컨테이너를 선택합니다. 이 문서에서는 스토리지 계정과 IoT Hub를 동일한 지역에 배치하는 것이 좋습니다.

    • 사용하려는 스토리지 계정이 이미 있는 경우 목록에서 선택합니다.

    • 새 스토리지 계정을 만들려면 +스토리지 계정을 선택합니다. 스토리지 계정에 대한 이름을 제공하고 위치가 IoT 허브와 동일한 지역으로 설정되었는지 확인한 다음, 확인을 선택합니다. 새 계정은 IoT 허브와 동일한 리소스 그룹에 만들어집니다. 배포가 완료되면 목록에서 스토리지 계정을 선택합니다.

    스토리지 계정을 선택하면 컨테이너 창이 열립니다.

  3. 컨테이너 창에서 Blob 컨테이너를 선택합니다.

    • 사용하려는 Blob 컨테이너가 이미 있는 경우 목록에서 선택하고 선택을 클릭합니다.

    • 새 Blob 컨테이너를 만들려면 + 컨테이너를 선택합니다. 새 컨테이너에 대한 이름을 제공합니다. 이 문서의 목적을 위해 다른 모든 필드를 기본값으로 그대로 둘 수 있습니다. 만들기를 선택합니다. 배포가 완료되면 목록에서 컨테이너를 선택하고 선택을 클릭합니다.

  4. 파일 업로드 창으로 다시 돌아가서 파일 알림이 켜짐으로 설정되었는지 확인합니다. 다른 모든 설정은 기본값으로 그대로 둘 수 있습니다. 저장을 선택하고 다음 섹션으로 이동하기 전에 설정이 완료될 때까지 기다립니다.

    Screen capture showing confirm file upload settings in the portal.

Azure Storage 계정을 만드는 방법에 대한 자세한 지침은 스토리지 계정 만들기를 참조하세요. 스토리지 계정 및 Blob 컨테이너를 IoT 허브와 연결하는 방법에 대한 자세한 지침은 Azure Portal을 사용하여 파일 업로드 구성을 참조하세요.

디바이스 앱의 파일 업로드

이 문서에서는 이전에 디바이스 앱으로서 다운로드한 Azure IoT C# 샘플 리포지토리에 있는 샘플을 사용합니다. Visual Studio, Visual Studio Code 또는 원하는 텍스트 편집기를 사용하여 아래 파일을 열 수 있습니다.

샘플은 Azure IoT C# 샘플을 추출한 폴더 아래의 azure-iot-samples-csharp-main\iot-hub\Samples\device\FileUploadSample에 있습니다.

FileUpLoadSample.cs에 있는 코드를 검사합니다. 이 파일에는 기본 샘플 논리가 포함되어 있습니다. 생성된 IoT Hub 디바이스 클라이언트는 디바이스의 파일을 업로드하는 표준 3단계 절차를 따릅니다.

  1. 코드에서 디바이스 클라이언트의 GetFileUploadSasUriAsync 메서드를 호출하여 IoT 허브에서 SAS URI를 얻습니다.

    var fileUploadSasUriRequest = new FileUploadSasUriRequest
    {
        BlobName = fileName
    };
    
    // Lines removed for clarity
    
    FileUploadSasUriResponse sasUri = await _deviceClient.GetFileUploadSasUriAsync(fileUploadSasUriRequest);
    Uri uploadUri = sasUri.GetBlobUri();
    
  2. 코드에서 SAS URI를 사용하여 Azure Storage에 파일을 업로드합니다. 이 샘플에서 코드는 SAS URI를 사용하여 Azure Storage 블록 Blob 클라이언트를 만들고 파일을 업로드합니다.

    var blockBlobClient = new BlockBlobClient(uploadUri);
    await blockBlobClient.UploadAsync(fileStreamSource, new BlobUploadOptions());
    
  3. 코드에서 업로드 완료를 IoT 허브에 알립니다. IoT 허브는 업로드와 관련된 리소스(SAS URI)를 해제할 수 있음을 알게 됩니다. 파일 업로드 알림을 사용 설정한 경우 IoT 허브는 백 엔드 서비스에 알림 메시지를 보냅니다.

    var successfulFileUploadCompletionNotification = new FileUploadCompletionNotification
    {
        // Mandatory. Must be the same value as the correlation id returned in the sas uri response
        CorrelationId = sasUri.CorrelationId,
    
        // Mandatory. Will be present when service client receives this file upload notification
        IsSuccess = true,
    
        // Optional, user defined status code. Will be present when service client receives this file upload notification
        StatusCode = 200,
    
        // Optional, user-defined status description. Will be present when service client receives this file upload notification
        StatusDescription = "Success"
    };
    
    await _deviceClient.CompleteFileUploadAsync(successfulFileUploadCompletionNotification);
    

parameter.cs 파일을 검사하면 다음을 확인하게 됩니다.

  • 샘플에서는 사용자가 디바이스 연결 문자열을 취하는 매개 변수인 p를 전달해야 합니다.

  • 기본적으로 디바이스 샘플은 MQTT 프로토콜을 사용하여 IoT Hub와 통신합니다. t 매개 변수를 사용하여 이 전송 프로토콜을 변경할 수 있습니다. 하지만 무엇을 선택하더라도 Azure Blob 클라이언트에서는 항상 HTTPS를 프로토콜로 사용하여 파일을 Azure Storage에 업로드합니다.

IoT Hub 연결 문자열 가져오기

이 문서에서는 사용자의 IoT 허브에서 파일 업로드 알림 메시지를 수신하는 백 엔드 서비스를 만듭니다. 파일 업로드 알림 메시지를 수신하려면 서비스에 서비스 연결 권한이 있어야 합니다. 기본적으로 모든 IoT Hub는 이 사용 권한을 부여하는 service라는 공유 액세스 정책을 사용하여 만듭니다.

service 정책에 대한 IoT Hub 연결 문자열을 가져오려면 다음 단계를 수행합니다.

  1. Azure Portal에서 리소스 그룹을 선택합니다. 허브가 있는 리소스 그룹을 선택한 다음, 리소스 목록에서 허브를 선택합니다.

  2. IoT Hub의 왼쪽 창에서 공유 액세스 정책을 선택합니다.

  3. 정책 목록에서 ervice 정책을 선택합니다.

  4. 공유 액세스 키아래에서 기본 연결 문자열의 복사 아이콘을 선택하고 값을 저장합니다.

Screenshot that shows how to retrieve the connection string

IoT Hub 공유 액세스 정책 및 사용 권한에 대한 자세한 내용은 액세스 제어 및 권한을 참조하세요.

파일 업로드 알림 수신

이 섹션에서는 사용자의 IoT 허브에서 파일 업로드 알림 메시지를 수신하는 C# 콘솔 앱을 만듭니다.

  1. 명령 창을 열고 프로젝트를 만들 폴더로 이동합니다. ReadFileUploadNotifications라는 이름의 폴더를 만들고 디렉터리를 이 폴더로 변경합니다.

    mkdir ReadFileUploadNotification
    cd ReadFileUploadNotification
    
  2. 다음 명령을 실행하여 C# 콘솔 프로젝트를 만듭니다. 명령을 실행하면 폴더에는 Program.cs 파일과 ReadFileUploadNotification.csproj 파일이 포함됩니다.

    dotnet new console --language c#
    
  3. 다음 명령을 실행하여 Microsoft.Azure.Devices 패키지를 프로젝트 파일에 추가합니다. 이 패키지는 Azure IoT .NET 서비스 SDK입니다.

    dotnet add package Microsoft.Azure.Devices
    
  4. Program.cs 파일을 열고 파일 맨 위에 다음 문을 추가합니다.

    using Microsoft.Azure.Devices;
    
  5. Program 클래스에 다음 필드를 추가합니다. 자리 {iot hub connection string} 표시자 값을 이전에 IoT Hub 연결 문자열 얻기에서 복사한 {iot hub connection string}대체합니다.

    static ServiceClient serviceClient;
    static string connectionString = "{iot hub connection string}";
    
  6. Program 클래스에 다음 메서드를 추가합니다.

    private async static void ReceiveFileUploadNotificationAsync()
    {
        var notificationReceiver = serviceClient.GetFileNotificationReceiver();
        Console.WriteLine("\nReceiving file upload notification from service");
        while (true)
        {
            var fileUploadNotification = await notificationReceiver.ReceiveAsync();
            if (fileUploadNotification == null) continue;
            Console.ForegroundColor = ConsoleColor.Yellow;
            Console.WriteLine("Received file upload notification: {0}", 
              string.Join(", ", fileUploadNotification.BlobName));
            Console.ResetColor();
            await notificationReceiver.CompleteAsync(fileUploadNotification);
        }
    }
    

    수신 패턴은 디바이스 앱으로부터 클라우드-디바이스 메시지를 받는 데 사용되는 것과 동일합니다.

  7. 마지막으로 Main 메서드의 줄을 다음 줄로 바꿉니다.

    Console.WriteLine("Receive file upload notifications\n");
    serviceClient = ServiceClient.CreateFromConnectionString(connectionString);
    ReceiveFileUploadNotificationAsync();
    Console.WriteLine("Press Enter to exit\n");
    Console.ReadLine();
    

애플리케이션 실행

이제 애플리케이션을 실행할 준비가 되었습니다.

  1. 먼저 서비스 앱을 실행하여 IoT 허브에서 파일 업로드 알림을 받습니다. ReadFileUploadNotification 폴더의 명령 프롬프트에서 다음 명령을 실행합니다.

    dotnet restore
    dotnet run
    

    앱이 시작되고 IoT 허브에서 파일 업로드 알림이 도착하길 기다립니다.

    Receive file upload notifications
    
    
    Receiving file upload notification from service
    Press Enter to exit
    
  2. 디바이스 앱을 실행하여 Azure Storage에 파일을 업로드합니다. 새 명령 프롬프트를 열고 폴더를 Azure IoT C# 샘플을 확장한 폴더 아래의 azure-iot-samples-csharp-main\iot-hub\Samples\device\FileUploadSample로 변경합니다. 다음 명령을 실행합니다. 두 {Your device connection string} 번째 명령의 자리 표시자 값을 이전에 {Your device connection string}복사한 디바이스 연결 문자열로 대체합니다.

    dotnet restore
    dotnet run --p "{Your device connection string}"
    

    업로드가 완료되면 디바이스 앱에서 다음 출력이 생성됩니다.

      Uploading file TestPayload.txt
      Getting SAS URI from IoT Hub to use when uploading the file...
      Successfully got SAS URI (https://contosostorage.blob.core.windows.net/contosocontainer/MyDevice%2FTestPayload.txt?sv=2018-03-28&sr=b&sig=x0G1Baf%2BAjR%2BTg3nW34zDNKs07p6dLzkxvZ3ZSmjIhw%3D&se=2021-05-04T16%3A40%3A52Z&sp=rw) from IoT Hub
      Uploading file TestPayload.txt using the Azure Storage SDK and the retrieved SAS URI for authentication
      Successfully uploaded the file to Azure Storage
      Notified IoT Hub that the file upload succeeded and that the SAS URI can be freed.
      Time to upload file: 00:00:01.5077954.
      Done.
    
  3. 파일 업로드 알림이 수신되었다는 메시지가 서비스 앱에 표시됩니다.

    Receive file upload notifications
    
    
    Receiving file upload notification from service
    Press Enter to exit
    
    Received file upload notification: myDeviceId/TestPayload.txt
    

파일 업로드 확인

포털을 사용하면 구성한 스토리지 컨테이너에 업로드된 파일을 볼 수 있습니다.

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

  2. 스토리지 계정의 왼쪽 창에서 컨테이너를 선택합니다.

  3. 파일을 업로드한 컨테이너를 선택합니다.

  4. 디바이스 이름을 딴 폴더를 선택합니다.

  5. 파일을 업로드한 Blob을 선택합니다. 이 문서에서는 TestPayload.txt라는 이름의 Blob입니다.

    Screenshot of selecting the uploaded file in the Azure portal.

  6. 열리는 페이지에서 Blob 속성을 확인합니다. 다운로드를 선택하여 파일을 다운로드하고 로컬에서 파일 내용을 볼 수 있습니다.

다음 단계

이 자습서에서는 디바이스에서 파일 업로드를 단순화하기 위해 IoT Hub의 파일 업로드 기능을 사용하는 방법을 알아보았습니다. 다음 문서에서 이 기능을 계속 탐색할 수 있습니다.