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

아티클
03/04/2024

이 문서에서는 Azure IoT .NET 디바이스 및 서비스 SDK를 사용하여 IoT Hub의 파일 업로드 기능에서 파일을 Azure Blob 스토리지에 업로드하는 방법을 보여 줍니다.

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

비디오
이미지가 포함된 대형 파일
자주 샘플링되는 진동 데이터
특정 형태의 전처리된 데이터

이러한 파일은 일반적으로 Azure Data Factory 또는 Hadoop 스택과 같은 도구를 사용하여 클라우드에서 일괄 처리됩니다. 디바이스에서 파일을 업로드해야 할 때 IoT Hub의 보안 및 안정성을 여전히 사용할 수 있습니다. 이 문서에서 그 방법을 보여줍니다.

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

FileUploadSample 이 디바이스 앱은 IoT 허브에서 제공하는 SAS URI를 사용하여 스토리지에 파일을 업로드합니다. 이 샘플은 필수 구성 요소에서 다운로드하는 Azure IoT C# SDK 리포지토리에서 가져옵니다.
ReadFileUploadNotification. 이 서비스 앱은 IoT 허브에서 파일 업로드 알림을 받습니다. 이 앱을 만듭니다.

참고 항목

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

Important

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

필수 조건

IoT 허브. CLI 또는 Azure Portal을 사용하여 만듭니다.
등록된 디바이스. Azure Portal에 하나를 등록합니다.
이 문서에서 실행하는 샘플 애플리케이션은 .NET Core에서 C#을 사용하여 작성되었습니다.

.NET에서 여러 플랫폼용 .NET Core SDK를 다운로드합니다.

다음 명령을 사용하여 개발 컴퓨터에서 .NET Core SDK의 현재 버전을 확인합니다.
```
dotnet --version
```
샘플 다운로드에서 Azure IoT C# SDK를 다운로드하고 ZIP 보관 파일의 압축을 풉니다.
8883 포트는 방화벽에서 열려 있어야 합니다. 이 문서의 샘플은 포트 8883을 통해 통신하는 MQTT 프로토콜을 사용합니다. 이 포트는 일부 회사 및 교육용 네트워크 환경에서 차단될 수 있습니다. 이 문제를 해결하는 자세한 내용과 방법은 IoT Hub에 연결(MQTT)을 참조하세요.

Azure Storage 계정을 IoT Hub에 연결

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

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

허브 설정 아래에서 사용자 IoT 허브의 왼쪽에 있는 파일 업로드를 선택합니다.
파일 업로드 창에서 Azure Storage 컨테이너를 선택합니다. 이 문서에서는 스토리지 계정과 IoT Hub를 동일한 지역에 배치하는 것이 좋습니다.
- 사용하려는 스토리지 계정이 이미 있는 경우 목록에서 선택합니다.
- 새 스토리지 계정을 만들려면 +스토리지 계정을 선택합니다. 스토리지 계정에 대한 이름을 제공하고 위치가 IoT 허브와 동일한 지역으로 설정되었는지 확인한 다음, 확인을 선택합니다. 새 계정은 IoT 허브와 동일한 리소스 그룹에 만들어집니다. 배포가 완료되면 목록에서 스토리지 계정을 선택합니다.
스토리지 계정을 선택하면 컨테이너 창이 열립니다.
컨테이너 창에서 Blob 컨테이너를 선택합니다.
- 사용하려는 Blob 컨테이너가 이미 있는 경우 목록에서 선택하고 선택을 클릭합니다.
- 새 Blob 컨테이너를 만들려면 + 컨테이너를 선택합니다. 새 컨테이너에 대한 이름을 제공합니다. 이 문서의 목적을 위해 다른 모든 필드를 기본값으로 그대로 둘 수 있습니다. 만들기를 실행합니다. 배포가 완료되면 목록에서 컨테이너를 선택하고 선택을 클릭합니다.
파일 업로드 창으로 다시 돌아가서 파일 알림이 켜짐으로 설정되었는지 확인합니다. 다른 모든 설정은 기본값으로 그대로 둘 수 있습니다. 저장을 선택하고 다음 섹션으로 이동하기 전에 설정이 완료될 때까지 기다립니다.

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

디바이스 앱의 파일 업로드

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

샘플은 Azure IoT C# SDK를 추출한 폴더의 azure-iot-sdk-csharp/iothub/device/samples/getting started/FileUploadSample에 있습니다.

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

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

var fileUploadSasUriRequest = new FileUploadSasUriRequest
{
    BlobName = fileName
};

// Lines removed for clarity

FileUploadSasUriResponse sasUri = await _deviceClient.GetFileUploadSasUriAsync(fileUploadSasUriRequest);
Uri uploadUri = sasUri.GetBlobUri();

코드에서 SAS URI를 사용하여 Azure Storage에 파일을 업로드합니다. 이 샘플에서 코드는 SAS URI를 사용하여 Azure Storage 블록 Blob 클라이언트를 만들고 파일을 업로드합니다.
```
var blockBlobClient = new BlockBlobClient(uploadUri);
await blockBlobClient.UploadAsync(fileStreamSource, new BlobUploadOptions());
```

코드에서 업로드 완료를 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 스토리지에 업로드합니다.

IoT Hub 연결 문자열 가져오기

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

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

Azure Portal에서 리소스 그룹을 선택합니다. 허브가 있는 리소스 그룹을 선택한 다음, 리소스 목록에서 허브를 선택합니다.
IoT Hub의 왼쪽 창에서 공유 액세스 정책을 선택합니다.
정책 목록에서 ervice 정책을 선택합니다.
기본 연결 문자열을 복사하고 값을 저장합니다.

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

파일 업로드 알림 수신

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

명령 창을 열고 프로젝트를 만들 폴더로 이동합니다. ReadFileUploadNotifications라는 이름의 폴더를 만들고 디렉터리를 이 폴더로 변경합니다.
```
mkdir ReadFileUploadNotification
cd ReadFileUploadNotification
```
다음 명령을 실행하여 C# 콘솔 프로젝트를 만듭니다. 명령을 실행하면 폴더에는 Program.cs 파일과 ReadFileUploadNotification.csproj 파일이 포함됩니다.
```
dotnet new console --language c#
```
다음 명령을 실행하여 Microsoft.Azure.Devices 패키지를 프로젝트 파일에 추가합니다. 이 패키지는 Azure IoT .NET 서비스 SDK입니다.
```
dotnet add package Microsoft.Azure.Devices
```
Program.cs 파일을 열고 파일 맨 위에 다음 문을 추가합니다.
```
using Microsoft.Azure.Devices;
```
Program 클래스에 다음 필드를 추가합니다. {iot hub connection string} 자리 표시자 값을 이전에 IoT Hub 연결 문자열 가져오기에서 복사한 IoT Hub 연결 문자열로 바꿉니다.
```
static ServiceClient serviceClient;
static string connectionString = "{iot hub connection string}";
```

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);
    }
}

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

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

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

애플리케이션 실행

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

먼저 서비스 앱을 실행하여 IoT 허브에서 파일 업로드 알림을 받습니다. ReadFileUploadNotification 폴더의 명령 프롬프트에서 다음 명령을 실행합니다.
```
dotnet restore
dotnet run
```
앱이 시작되고 IoT 허브에서 파일 업로드 알림이 도착하길 기다립니다.
```
Receive file upload notifications


Receiving file upload notification from service
Press Enter to exit
```

디바이스 앱을 실행하여 Azure Storage에 파일을 업로드합니다. Azure IoT C# SDK를 확장한 폴더에서 새 명령 프롬프트를 열고 폴더를 azure-iot-sdk-csharp\iothub\device\samples\getting started\FileUploadSample로 변경합니다. 다음 명령을 실행합니다. 두 번째 명령의 {Your device connection string} 자리 표시자 값을 IoT 허브에 디바이스를 등록할 때 해당 디바이스 연결 문자열로 바꿉니다.

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.

파일 업로드 알림이 수신되었다는 메시지가 서비스 앱에 표시됩니다.

Receive file upload notifications


Receiving file upload notification from service
Press Enter to exit

Received file upload notification: myDeviceId/TestPayload.txt

파일 업로드 확인

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

Azure Portal에서 스토리지 계정으로 이동합니다.
스토리지 계정의 왼쪽 창에서 컨테이너를 선택합니다.
파일을 업로드한 컨테이너를 선택합니다.
디바이스 이름을 딴 폴더를 선택합니다.
파일을 업로드한 Blob을 선택합니다. 이 문서에서는 TestPayload.txt라는 이름의 Blob입니다.
열리는 페이지에서 Blob 속성을 확인합니다. 다운로드를 선택하여 파일을 다운로드하고 로컬에서 파일 내용을 볼 수 있습니다.

다음 단계

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