IoT Hub를 사용하여 파일 업로드

아티클
03/09/2023

IoT Hub에서 허용하는 비교적 작은 디바이스-클라우드 메시지에 디바이스 데이터를 쉽게 매핑할 수 없는 시나리오가 많이 있습니다. 예를 들면 비디오와 같은 대용량 미디어 파일을 보내는 경우 또는 간헐적으로 연결된 디바이스에서 업로드하거나 대역폭을 절약하기 위해 집계/압축된 대규모 원격 분석 일괄 처리를 보내는 경우가 있습니다.

디바이스에서 대용량 파일을 업로드해야 할 때에도 IoT Hub의 보안 성능과 안정성을 사용할 수 있습니다. 그러나 IoT Hub는 자체적으로 메시지를 중개하는 대신 연결된 Azure Storage 계정에 대한 디스패처 역할을 합니다. IoT Hub에서는 디바이스가 파일 업로드를 완료할 때 백 엔드 서비스에 알림도 제공할 수 있습니다.

보고된 속성, 디바이스-클라우드 메시지 또는 파일 업로드 사용 시기를 결정하는 데 도움이 필요한 경우 디바이스-클라우드 통신 참고 자료를 참조하세요.

Important

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

파일 업로드 개요

IoT 허브는 허브를 사용하여 미리 구성된 Blob 컨테이너 및 Azure Storage 계정에 대해 업로드당 SAS(공유 액세스 서명) URI를 제공함으로써 연결된 디바이스에서 용이하게 파일을 업로드할 수 있도록 합니다. IoT Hub에서 파일 업로드를 사용하는 부분으로는 IoT 허브에서 Azure Storage 계정 및 Blob 컨테이너를 미리 구성하고, 디바이스에서 파일을 업로드하며, 필요에 따라 백 엔드 서비스에 완료된 파일 업로드를 알리는 등의 세 가지가 있습니다.

파일 업로드 기능을 사용하려면 먼저 Azure Storage 계정 및 Blob 컨테이너를 IoT Hub와 연결해야 합니다. IoT Hub가 Azure Storage를 사용하여 인증하는 방법, IoT Hub가 디바이스에 전달하는 SAS URI의 TTL(Time to Live), 백 엔드 서비스에 대한 파일 업로드 알림을 제어하는 설정도 구성할 수 있습니다. 자세히 알아보려면 Azure Storage 계정을 IoT Hub와 연결을 참조하세요.

디바이스는 다음의 3단계 프로세스에 따라 연결된 Blob 컨테이너에 파일을 업로드합니다.

디바이스에서 IoT Hub를 사용하여 파일 업로드를 시작합니다. 요청에서 Blob의 이름을 전달하고 대신 SAS URI 및 상관 관계 ID를 가져옵니다. SAS URI에는 Blob 컨테이너에서 요청된 Blob에 대한 디바이스 읽기-쓰기 권한을 부여하는 Azure Storage용 SAS 토큰이 포함되어 있습니다. 자세한 내용은 디바이스: 파일 업로드 초기화를 참조하세요.
디바이스는 SAS URI를 사용해 Azure Blob Storage API를 안전하게 호출하여 Blob 컨테이너에 파일을 업로드합니다. 자세한 내용은 디바이스: Azure Storage API를 사용하여 파일 업로드를 참조하세요.
파일 업로드가 완료되면 디바이스가 업로드를 시작할 때 IoT Hub에서 받은 상관 관계 ID를 사용하여 IoT Hub에 완료 상태를 알립니다. 자세한 내용은 디바이스: 완료된 파일 업로드를 IoT Hub에 알림을 참조하세요.

백 엔드 서비스는 IoT Hub의 서비스 연결 파일 업로드 알림 엔드포인트에서 파일 업로드 알림을 구독할 수 있습니다. IoT Hub에서 이러한 알림을 사용하도록 설정한 경우, 디바이스가 파일 업로드를 완료했음을 허브에 알할 때마다 이 엔드포인트에 알림을 전달합니다. 서비스는 이러한 알림을 사용하여 Blob 데이터의 추가 처리를 트리거할 수 있습니다. 자세한 내용은 서비스: 파일 업로드 알림을 참조하세요.

파일 업로드는 Azure IoT 디바이스 및 서비스 SDK에서 전적으로 지원됩니다. 자세한 내용은 SDK를 사용하여 파일 업로드를 참조하세요.

파일 업로드 할당량 및 한도

IoT Hub는 지정된 기간 동안 시작할 수 있는 파일 업로드 수에 제한을 적용합니다. 임계값은 SKU 및 IoT Hub의 단위 수를 기준으로 합니다. 또한 각 디바이스는 한 번에 10개의 동시 활성 파일 업로드로 제한됩니다. 자세한 내용은 IoT Hub 할당량 및 제한을 참조하세요.

Azure Storage 계정을 IoT Hub와 연결

파일 업로드 기능을 사용하려면 Azure Storage 계정 및 Blob 컨테이너를 IoT 허브와 연결해야 합니다. IoT Hub에 등록된 디바이스의 모든 파일 업로드는 이 컨테이너로 이동됩니다. IoT 허브에서 스토리지 계정 및 Blob 컨테이너를 구성하려면 Azure Portal을 사용하여 IoT Hub 파일 업로드 구성, Azure CLI를 사용하여 IoT Hub 파일 업로드 구성 또는 PowerShell을 사용하여 IoT Hub 파일 업로드 구성을 참조하세요. 또한 IoT Hub 관리 API를 사용하여 프로그래밍 방식으로 파일 업로드를 구성할 수 있습니다.

포털을 사용하는 경우, 구성 중에 스토리지 계정과 컨테이너를 만들 수 있습니다. 그렇지 않은 경우 스토리지 계정을 만들려면 Azure Storage 설명서에서 스토리지 계정 만들기를 참조하세요. 스토리지 계정이 있으면 Azure Blob Storage 빠른 시작에서 Blob 컨테이너를 만드는 방법을 확인할 수 있습니다. 기본적으로 Azure IoT Hub는 키 기반 인증을 사용하여 Azure Storage에 연결하고 권한을 부여합니다. Azure Storage로 Azure IoT Hub를 인증하도록 사용자가 할당한 관리 ID 또는 시스템이 할당한 관리 ID를 구성할 수도 있습니다. 관리 ID는 Microsoft Entra ID에서 자동으로 관리되는 ID를 안전한 방식으로 Azure 서비스에 제공합니다. 관리 ID를 구성하는 방법을 알아보려면 관리 ID에 대한 IoT Hub 지원의 관리 ID를 사용하여 파일 업로드 구성 섹션을 참조하세요.

파일 업로드에는 Azure Storage의 방화벽 설정이 적용됩니다. 인증 구성에 따라 디바이스가 Azure Storage와 통신할 수 있는지 확인해야 합니다.

파일 업로드 및 파일 업로드 알림의 동작을 제어하는 다른 설정이 몇 가지 있습니다. 다음 섹션에는 사용 가능한 모든 설정이 나열되어 있습니다. 파일 업로드를 구성하는 데 Azure Portal을 사용하는지, 아니면 Azure CLI, PowerShell 또는 관리 API를 사용하는지에 따라 이러한 설정 중 일부를 사용하지 못할 수도 있습니다. 파일 업로드가 완료될 때 백 엔드 서비스에 알림을 보내려면 enableFileUploadNotifications 설정을 지정해야 합니다.

IoT Hub 스토리지 및 인증 설정

다음 설정은 스토리지 계정 및 컨테이너를 IoT Hub와 연결하고, 허브에서 Azure Storage를 사용하여 인증하는 방법을 제어합니다. 이러한 설정은 디바이스가 Azure Storage를 사용하여 인증하는 방법에 영향을 주지 않습니다. 디바이스는 항상 IoT Hub에서 검색된 SAS URI에 표시되는 SAS 토큰을 사용하여 인증합니다.

속성	설명	범위 및 기본값
storageEndpoints.$default.authenticationType	IoT Hub가 Azure Storage를 사용하여 인증하는 방법을 제어합니다.	가능한 값은 keyBased 및 identityBased입니다. 기본값: keyBased
storageEndpoints.$default.connectionString	파일 업로드에서 사용할 Azure Storage 계정에 대한 연결 문자열입니다.	기본값: 빈 문자열입니다.
storageEndpoints.$default.containerName	파일을 업로드할 컨테이너의 이름입니다.	기본값: 빈 문자열입니다.
storageEndpoints.$default.identity	ID 기반 인증에서 사용할 관리 ID입니다.	가능한 값은 시스템 할당 관리 ID의 `[system]` 또는 사용자 할당 관리 ID의 리소스 ID입니다. 값은 키 기반 인증에 사용되지 않습니다. 기본값: Null

파일 업로드 설정

다음 설정은 디바이스에서 파일 업로드를 제어합니다.

속성	설명	범위 및 기본값
storageEndpoints.$default.ttlAsIso8601	IoT Hub에서 생성된 SAS URI에 대한 기본 TTL입니다.	ISO_8601 간격은 최대 48시간(최소 1분)입니다. 기본값: 1시간입니다.

파일 업로드 알림 설정

다음 설정은 백 엔드 서비스에 대한 파일 업로드 알림을 제어합니다.

속성	설명	범위 및 기본값
enableFileUploadNotifications	파일 업로드 알림이 파일 알림 엔드포인트에 작성되는지를 제어합니다.	Bool. 기본값: False입니다.
fileNotifications.ttlAsIso8601	파일 업로드 알림에 대한 기본 TTL입니다.	ISO_8601 간격은 최대 48시간(최소 1분)입니다. 기본값: 1시간입니다.
fileNotifications.lockDuration	파일 업로드 알림 큐에 대한 잠금 기간입니다.	5~300초 기본값은 60초입니다.
fileNotifications.maxDeliveryCount	파일 업로드 알림 큐에 대한 최대 배달 횟수입니다.	1에서 100까지입니다. 기본값은 10입니다.

SDK를 사용하여 파일 업로드

다음 방법 가이드에서는 Azure IoT 디바이스와 서비스 SDK를 사용해 파일을 업로드하는 전체 단계별 지침을 제공합니다. 이러한 가이드에서는 Azure Portal을 사용하여 스토리지 계정을 IoT 허브와 연결하는 방법을 보여 줍니다. 또한 코드 조각을 포함하거나 업로드를 안내하는 샘플을 참조합니다.

방법 가이드	디바이스 SDK 예제	서비스 SDK 예제
.NET	예	예
Java	예	예
Node.JS	예	예
Python	예	아니요(지원되지 않음)

참고 항목

C 디바이스 SDK는 디바이스 클라이언트에서 단일 호출을 사용하여 파일을 업로드합니다. 자세한 내용은 IoTHubDeviceClient_UploadToBlobAsync() 및 IoTHubDeviceClient_UploadMultipleBlocksToBlobAsync()를 참조하세요. 이러한 함수는 업로드를 시작하고, Azure Storage에 파일을 업로드하며, 완료되면 IoT Hub에 알리는 등 단일 호출에서 파일 업로드의 모든 측면을 수행합니다. 이러한 상호 작용은 디바이스가 IoT Hub와 통신하는 데 사용하는 프로토콜뿐만 아니라 이러한 함수는 Azure Storage API를 호출하므로 디바이스가 Azure Storage와 HTTPS를 통해 통신할 수도 있어야 합니다.

디바이스: 파일 업로드 초기화

디바이스는 파일 업로드 SAS URI 만들기 REST API 또는 디바이스 SDK 중 하나에 해당하는 API를 호출하여 파일 업로드를 시작합니다.

지원되는 프로토콜: HTTPS
엔드포인트: {iot hub}.azure-devices.net/devices/{deviceId}/files
메서드: POST

{
    "blobName":"myfile.txt"
}

속성	설명
blobName	SAS URI를 생성할 Blob의 이름입니다.

IoT Hub는 디바이스가 Azure Storage를 인증하는 데 사용할 수 있는 SAS URI의 요소 및 상관 관계 ID로 응답합니다. 이 응답에는 대상 IoT Hub의 제한 한도 및 디바이스당 업로드 한도가 적용됩니다.

{
    "correlationId":"MjAyMTA3MzAwNjIxXzBiNjgwOGVkLWZjNzQtN...MzYzLWRlZmI4OWQxMzdmNF9teWZpbGUudHh0X3ZlcjIuMA==",
    "hostName":"contosostorageaccount.blob.core.windows.net",
    "containerName":"device-upload-container",
    "blobName":"mydevice/myfile.txt",
    "sasToken":"?sv=2018-03-28&sr=b&sig=mBLiODhpKXBs0y9RVzwk1S...l1X9qAfDuyg%3D&se=2021-07-30T06%3A11%3A10Z&sp=rw"
}

속성	설명
correlationId	IoT Hub에 파일 업로드 전체 알림을 보낼 때 사용할 디바이스의 식별자입니다.
hostName	IoT Hub에 구성된 스토리지 계정의 Azure Storage 계정 호스트 이름
containerName	IoT Hub에 구성된 Blob 컨테이너의 이름입니다.
blobName	Blob이 컨테이너에 저장될 위치입니다. 이름의 형식은 `{device ID of the device making the request}/{blobName in the request}`입니다.
sasToken	Azure Storage를 사용하여 Blob에 대한 읽기-쓰기 액세스 권한을 부여하는 SAS 토큰입니다. 토큰은 IoT Hub에서 생성 및 서명됩니다.

응답을 받으면 디바이스에서 다음을 수행합니다.

업로드를 완료하면 파일 업로드 완료 알림에 포함할 상관 관계 ID를 IoT Hub에 저장합니다.
다른 속성을 사용하여 Azure Storage를 인증하는 데 사용하는 Blob의 SAS URI를 생성합니다. SAS URI에는 요청된 Blob 및 SAS 토큰에 대한 리소스 URI가 포함됩니다. https://{hostName}/{containerName}/{blobName}{sasToken} 형식(응답의 sasToken 속성에는 선행 '?' 문자가 포함됨)을 사용합니다. 중괄호는 포함되지 않습니다.

예를 들어 이전 샘플에서 반환된 값의 경우 SAS URI는 https://contosostorageaccount.blob.core.windows.net/device-upload-container/mydevice/myfile.txt?sv=2018-03-28&sr=b&sig=mBLiODhpKXBs0y9RVzwk1S...l1X9qAfDuyg%3D&se=2021-07-30T06%3A11%3A10Z&sp=rw입니다.

SAS URI 및 SAS 토큰에 대한 자세한 내용은 Azure Storage 설명서에서 서비스 SAS 만들기를 참조하세요.

디바이스: Azure Storage API를 사용하여 파일 업로드

디바이스는 Azure Blob Storage REST API 또는 해당하는 Azure Storage SDK API를 사용하여 Azure Storage의 Blob에 파일을 업로드합니다.

지원되는 프로토콜: HTTPS

다음 예제는 작은 블록 Blob을 만들거나 업데이트하기 위한 Blob 배치 요청을 보여 줍니다. 이 요청에 사용되는 URI는 이전 섹션에서 IoT Hub가 반환한 SAS URI입니다. x-ms-blob-type 헤더는 이 요청이 블록 Blob에 대한 것임을 나타냅니다. 요청이 성공하면 Azure Storage에서 201 Created를 반환합니다.

PUT https://contosostorageaccount.blob.core.windows.net/device-upload-container/mydevice/myfile.txt?sv=2018-03-28&sr=b&sig=mBLiODhpKXBs0y9RVzwk1S...l1X9qAfDuyg%3D&se=2021-07-30T06%3A11%3A10Z&sp=rw HTTP/1.1
Content-Length: 11
Content-Type: text/plain; charset=UTF-8
Host: contosostorageaccount.blob.core.windows.net
x-ms-blob-type: BlockBlob

hello world

Azure Storage API로 작업하는 것은 이 문서의 범위를 벗어납니다. 이 섹션의 앞부분에 연결된 Azure Blob Storage REST API 외에 다음과 같은 설명서를 살펴보면 시작하는 데 도움을 받을 수 있습니다.

Azure Storage에서 Blob을 사용하는 방법을 자세히 알아보려면 Azure Blob Storage 설명서를 참조하세요.
Azure Storage 클라이언트 SDK를 사용하여 Blob을 업로드하는 방법에 대한 자세한 내용은 Azure Blob Storage API 참조를 참조하세요.

디바이스: 완료된 파일 업로드를 IoT Hub에 알림

디바이스는 파일 업로드를 완료할 때 디바이스 SDK 중 하나에 해당하는 API 또는 파일 업로드 상태 업데이트 REST API를 호출합니다. 디바이스는 업로드에 성공하든, 실패하든 상관없이 IoT Hub로 파일 업로드 상태를 업데이트해야 합니다.

지원되는 프로토콜: HTTPS
엔드포인트: {iot hub}.azure-devices.net/devices/{deviceId}/files/notifications
메서드: POST

{
    "correlationId": "MjAyMTA3MzAwNjIxXzBiNjgwOGVkLWZjNzQtN...MzYzLWRlZmI4OWQxMzdmNF9teWZpbGUudHh0X3ZlcjIuMA==",
    "isSuccess": true,
    "statusCode": 200,
    "statusDescription": "File uploaded successfully"
}

속성	설명
correlationId	초기 SAS URI 요청에서 받은 상관 관계 ID입니다.
isSuccess	파일 업로드가 성공했는지 여부를 나타내는 부울입니다.
statusCode	파일 업로드의 상태 코드를 나타내는 정수입니다. 일반적으로 3자리 숫자(예: 200 또는 201)입니다.
statusDescription	파일 업로드 상태에 대한 설명입니다.

디바이스에서 파일 업로드 전체 알림을 받으면 IoT Hub에서 다음을 수행합니다.

파일 업로드 알림이 구성된 경우 백 엔드 서비스에 파일 업로드 알림을 트리거합니다.
파일 업로드와 관련된 리소스를 릴리스합니다. IoT Hub에서 알림을 받지 못하면 업로드와 연결된 SAS URI TTL(Time to Live)이 만료될 때까지 리소스를 유지 관리합니다.

서비스: 파일 업로드 알림

IoT 허브에서 파일 업로드 알림을 사용하도록 설정한 경우, 디바이스에서 파일 업로드가 완료되었다는 알림을 받으면 백 엔드 서비스에 대한 알림 메시지를 생성합니다. IoT Hub는 서비스 연결 엔드포인트를 통해 이러한 파일 업로드 알림을 전달합니다. 파일 업로드 알림에 대한 수신 의미 체계는 클라우드-디바이스 메시지의 경우와 동일하며 동일한 메시지 수명 주기를 갖습니다. 서비스 SDK는 API를 노출하여 파일 업로드 알림을 처리합니다.

지원되는 프로토콜 AMQP, AMQP-WS
엔드포인트: {iot hub}.azure-devices.net/messages/servicebound/fileuploadnotifications
메서드 GET

파일 업로드 알림 엔드포인트에서 검색된 각 메시지는 다음과 같은 JSON 레코드입니다.

{
    "deviceId":"mydevice",
    "blobUri":"https://contosostorageaccount.blob.core.windows.net/device-upload-container/mydevice/myfile.txt",
    "blobName":"mydevice/myfile.txt",
    "lastUpdatedTime":"2021-07-31T00:26:50+00:00",
    "blobSizeInBytes":11,
    "enqueuedTimeUtc":"2021-07-31T00:26:51.5134008Z"
}

속성	설명
enqueuedTimeUtc	알림을 만든 시간을 나타내는 타임스탬프입니다.
deviceId	파일을 업로드한 디바이스의 디바이스 ID입니다.
blobUri	업로드된 파일의 URI입니다.
blobName	업로드된 파일의 이름입니다. 이름의 형식은 `{device ID of the device}/{name of the blob}`입니다.
lastUpdatedTime	파일이 마지막으로 업데이트된 시간을 나타내는 타임스탬프입니다.
blobSizeInBytes	업로드된 파일의 크기를 바이트 단위로 나타내는 정수입니다.

서비스는 알림을 사용하여 업로드를 관리할 수 있습니다. 예를 들어 Blob 데이터의 자체 처리를 트리거하거나, 다른 Azure 서비스를 사용하여 Blob 데이터 처리를 트리거하거나, 나중에 검토할 수 있도록 파일 업로드 알림을 기록할 수 있습니다.

다음 단계

파일 업로드 방법 가이드
IoT Hub에서 파일 업로드를 구성하는 방법
IoT Hub에서 관리 ID를 구성하는 방법
Azure Blob Storage 설명서
Azure IoT 디바이스 및 서비스 SDK - IoT Hub와 상호 작용하는 디바이스 및 서비스 앱 모두를 개발할 때 사용할 수 있는 다양한 언어 SDK를 나열합니다.