다음을 통해 공유

Azure Functions에 대한 Azure IoT Hub 바인딩

  • 아티클

이 문서 집합에서는 IoT Hub에 대한 Azure Functions 바인딩을 사용하는 방법을 설명합니다. IoT Hub 지원은 Azure Event Hubs 바인딩을 기반으로 합니다.

Important

다음 코드 샘플에서는 Event Hub API를 사용하지만 지정된 구문은 IoT Hub 함수에 적용할 수 있습니다.

작업 Type
IoT 허브 이벤트 스트림으로 전송된 이벤트에 응답합니다. 트리거

확장 설치

설치하는 확장 NuGet 패키지는 함수 앱에서 사용 중인 C# 모드에 따라 다릅니다.

Functions는 격리된 C# 작업자 프로세스에서 실행됩니다. 자세한 내용은 격리된 작업자 프로세스에서 C# Azure Functions 실행 가이드를 참조하세요.

확장 기능의 기능은 확장 버전에 따라 다릅니다.

이 버전에는 비밀 대신 ID를 사용하여 연결하는 기능이 도입되었습니다. 관리 ID로 함수 앱을 구성하는 방법에 대한 자습서는 ID 기반 연결로 함수 앱 만들기 자습서를 참조하세요.

이 버전은 .NET Aspire 통합을 통해 트리거 및 바인딩의 구성을 지원합니다.

NuGet 패키지, 버전 5.x를 설치하여 프로젝트에 확장을 추가합니다.

번들 설치

Event Hubs 확장은 host.json 프로젝트 파일에 지정된 확장 번들의 일부입니다. 바인딩 버전을 변경하거나 번들이 아직 설치되지 않은 경우 이 번들을 수정해야 할 수 있습니다. 자세한 내용은 확장 번들을 참조하세요.

이 버전에는 비밀 대신 ID를 사용하여 연결하는 기능이 도입되었습니다. 관리 ID로 함수 앱을 구성하는 방법에 대한 자습서는 ID 기반 연결로 함수 앱 만들기 자습서를 참조하세요.

host.json 파일에서 다음 코드를 추가하거나 교체하여 확장 번들 v3에서 이 버전의 확장을 추가할 수 있습니다.

{
    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[3.3.0, 4.0.0)"
    }
}

자세한 내용은 확장 업데이트를 참조하세요.

바인딩 형식

.NET에 지원되는 바인딩 형식은 확장 버전과 C# 실행 모드 모두에 따라 달라지며 다음 옵션 중 하나일 수 있습니다.

격리된 작업자 프로세스 클래스 라이브러리 컴파일된 C# 함수는 런타임에서 격리된 프로세스에서 실행됩니다.

모드 및 버전에 대한 바인딩 형식 세부 정보를 보려면 버전을 선택합니다.

격리된 작업자 프로세스는 아래 표에 따라 매개 변수 형식을 지원합니다. Azure.Messaging.EventHubs의 형식에 대한 바인딩 지원은 미리 보기 상태입니다.

Event Hubs 트리거

함수가 단일 이벤트를 처리하도록 하려는 경우 Event Hubs 트리거는 다음 형식에 바인딩될 수 있습니다.

Type 설명
string 이벤트를 문자열로 지정합니다. 이벤트가 간단한 텍스트일 때 사용합니다.
byte[] 이벤트의 바이트입니다.
JSON 직렬화 가능 형식 이벤트에 JSON 데이터가 포함된 경우 Functions는 JSON 데이터를 POCO(Plain Old CLR Object) 형식으로 역직렬화하려고 합니다.
Azure.Messaging.EventHubs.EventData1 이벤트 개체입니다.
이전 버전의 Event Hubs SDK에서 마이그레이션하는 경우 이 버전에서는 BodyEventBody를 대신하여 레거시 형식에 대한 지원이 중단됩니다.

함수가 이벤트 일괄 처리를 수행하려는 경우 Event Hubs 트리거는 다음 형식에 바인딩될 수 있습니다.

Type 설명
string[] 일괄 처리의 이벤트 배열(문자열)입니다. 각 항목은 하나의 이벤트를 나타냅니다.
EventData[] 1 일괄 처리의 이벤트 배열(Azure.Messaging.EventHubs.EventData의 인스턴스)입니다. 각 항목은 하나의 이벤트를 나타냅니다.
T이(가) JSON 직렬화 가능 형식1인 T[] 사용자 지정 POCO 형식의 인스턴스인 일괄 처리의 이벤트 배열입니다. 각 항목은 하나의 이벤트를 나타냅니다.

1 이러한 형식을 사용하려면 Microsoft.Azure.Functions.Worker.Extensions.EventHubs 5.5.0 이상 및 SDK 형식 바인딩에 대한 공통 종속성을 참조해야 합니다.

Event Hubs 출력 바인딩

함수가 단일 이벤트를 작성하도록 하려는 경우 Event Hubs 출력 바인딩은 다음 형식에 바인딩될 수 있습니다.

Type 설명
string 이벤트를 문자열로 지정합니다. 이벤트가 간단한 텍스트일 때 사용합니다.
byte[] 이벤트의 바이트입니다.
JSON 직렬화 가능 형식 이벤트를 나타내는 개체입니다. 함수는 POCO(Plain Old CLR Object) 형식을 JSON 데이터로 직렬화하려고 시도합니다.

함수가 여러 이벤트를 작성하도록 하려는 경우 Event Hubs 출력 바인딩을 다음 형식에 바인딩할 수 있습니다.

Type 설명
T이(가) 단일 이벤트 유형 중 하나인 T[] 여러 이벤트를 포함하는 배열입니다. 각 항목은 하나의 이벤트를 나타냅니다.

다른 출력 시나리오의 경우 Azure.Messaging.EventHubs의 다른 형식과 함께 EventHubProducerClient를 직접 만들고 사용합니다. 종속성 주입을 사용하여 Azure SDK에서 클라이언트 형식을 만드는 예제는 Azure 클라이언트 등록을 참조하세요.

host.json 설정

host.json 파일에는 Event Hubs 트리거의 동작을 제어하는 설정이 포함되어 있습니다. 확장 버전에 따라 구성이 다릅니다.

{
    "version": "2.0",
    "extensions": {
        "eventHubs": {
            "maxEventBatchSize" : 100,
            "minEventBatchSize" : 25,
            "maxWaitTime" : "00:05:00",            
            "batchCheckpointFrequency" : 1,
            "prefetchCount" : 300,
            "transportType" : "amqpWebSockets",
            "webProxy" : "https://proxyserver:8080",
            "customEndpointAddress" : "amqps://company.gateway.local",
            "targetUnprocessedEventThreshold" : 75,
            "initialOffsetOptions" : {
                "type" : "fromStart",
                "enqueuedTimeUtc" : ""
            },
            "clientRetryOptions":{
                "mode" : "exponential",
                "tryTimeout" : "00:01:00",
                "delay" : "00:00:00.80",
                "maximumDelay" : "00:01:00",
                "maximumRetries" : 3
            }
        }
    }
}
속성 기본값 설명
maxEventBatchSize2 100 단일 호출에 대한 일괄 처리에 포함되는 최대 이벤트 수입니다. 최소한 1 이상이어야 합니다.
minEventBatchSize1 1 일괄 처리에서 원하는 최소 이벤트 수입니다. 최솟값은 함수가 여러 이벤트를 수신하고 maxEventBatchSize보다 작아야 하는 경우에만 적용됩니다.
최소 크기는 엄격하게 보장되지 않습니다. maxWaitTime이(가) 경과하기 전에 전체 일괄 처리를 준비할 수 없는 경우 부분 일괄 처리가 디스패치됩니다. 부분 일괄 처리는 크기 조정이 발생한 후 함수의 첫 번째 호출에 사용할 수도 있습니다.
maxWaitTime1 00:01:00 함수를 호출하기 전에 트리거가 일괄 처리를 채우기 위해 대기해야 하는 최대 간격입니다. 대기 시간은 minEventBatchSize이(가) 1보다 큰 경우에만 고려되고, 그렇지 않은 경우 무시됩니다. 대기 시간이 경과하기 전에 사용 가능한 이벤트가 minEventBatchSize보다 적은 경우 함수는 부분 일괄 처리로 호출됩니다. 허용되는 최대 대기 시간은 10분입니다.

참고: 이 간격은 함수가 호출되는 정확한 타이밍을 엄격하게 보장하지 않습니다. 타이머 정밀도로 인해 오차 범위가 작습니다. 크기 조정이 발생할 때 부분 일괄 처리가 있는 첫 번째 호출이 더 빠르게 발생하거나 구성된 대기 시간의 최대 두 배가 걸릴 수도 있습니다.
batchCheckpointFrequency 1 이벤트 허브에 대한 검사점을 만들기 전에 처리할 일괄 처리 수입니다.
prefetchCount 300 Event Hubs에서 적극적으로 요청되며, 네트워크 작업 대기를 피하기 위해 읽기를 허용하도록 로컬 캐시에 보관되는 이벤트 수
transportType amqpTcp Event Hubs와 통신하는 데 사용되는 프로토콜 및 전송입니다. 사용 가능한 옵션: amqpTcp, amqpWebSockets
webProxy null 웹 소켓을 통해 Event Hubs와 통신하는 데 사용할 프록시입니다. 프록시는 amqpTcp 전송과 함께 사용할 수 없습니다.
customEndpointAddress null Event Hubs에 대한 연결을 설정할 때 사용할 주소로 네트워크 요청이 애플리케이션 게이트웨이 또는 호스트 환경에 필요한 다른 경로를 통해 라우팅될 수 있습니다. 사용자 지정 엔드포인트 주소를 사용하는 경우에도 이벤트 허브에 대한 정규화된 네임스페이스가 필요하며 명시적으로 또는 연결 문자열 통해 지정해야 합니다.
targetUnprocessedEventThreshold1 null 함수 인스턴스당 처리되지 않은 이벤트의 원하는 수입니다. 임계값은 대상 기반 크기 조정에서 maxEventBatchSize 옵션에서 유추된 크기 조정 기본 임계값을 재정의하는 데 사용됩니다. 처리되지 않는 총 이벤트 수가 설정된 후에는 이 값으로 나누어져 필요한 함수 인스턴스 수를 결정합니다. 인스턴스 수는 분산된 파티션 배포를 만드는 숫자로 반올림됩니다.
initialOffsetOptions/type fromStart 검사점이 스토리지에 없을 때 처리를 시작할 이벤트 스트림의 위치입니다. 모든 파티션에 적용됩니다. 자세한 내용은 OffsetType 설명서를 참조하세요. 사용 가능한 옵션: fromStart, fromEnd, fromEnqueuedTime
initialOffsetOptions/enqueuedTimeUtc null 처리를 시작할 스트림에서 이벤트의 큐에 추가된 시간을 지정합니다. 로 fromEnqueuedTime구성된 경우 initialOffsetOptions/type 이 설정은 필수입니다. DateTime.Parse()에서 지원하는 모든 형식(예: 2020-10-26T20:31Z)의 시간을 지원합니다. 명확성을 위해 표준 시간대도 지정해야 합니다. 시간대가 지정되지 않은 경우 함수는 Azure에서 실행될 때 UTC인 함수 앱을 실행하는 머신의 로컬 시간대를 가정합니다.
clientRetryOptions/mode exponential 다시 시도 지연을 계산하는 데 사용하는 방법입니다. 지수 모드는 다시 시도하기 전 대기 시간, 즉 지연 시간이 늘어나는 백오프 전략에 기반하여 다시 시도합니다. 고정 모드는 각 지연의 지속 시간이 일정한 고정된 간격으로 다시 시도합니다. 사용 가능한 옵션: exponential, fixed
clientRetryOptions/tryTimeout 00:01:00 시도당 Event Hubs 작업이 완료될 때까지 대기하는 최대 기간입니다.
clientRetryOptions/delay 00:00:00.80 재시도 사이에 적용할 지연 또는 백오프 요소입니다.
clientRetryOptions/maximumDelay 00:00:01 다시 시도 사이에 허용되는 최대 지연입니다.
clientRetryOptions/maximumRetries 3 연결된 작업이 실패한 것으로 간주하기 전 최대 다시 시도 횟수입니다.

1minEventBatchSize 및 maxWaitTime을(를) 사용하려면 패키지Microsoft.Azure.WebJobs.Extensions.EventHubs의 v5.3.0 이상 버전이 필요합니다.

2Microsoft.Azure.WebJobs.Extensions.EventHubs 패키지의 v6.0.0에서 기본값 maxEventBatchSize가 변경되었습니다. 이전 버전에서는 10이었습니다.

함수 clientRetryOptions 호스트와 Event Hubs 간의 작업을 다시 시도하는 데 사용됩니다(예: 이벤트 가져오기 및 이벤트 보내기). 개별 함수에 다시 시도 정책을 적용하는 방법에 대한 자세한 내용은 Azure Functions 오류 처리 및 다시 시도에 대한 지침을 참조하세요.

Azure Functions 2.x 이상에서 host.json 대한 참조는 Azure Functions에 대한 host.json 참조를 참조 하세요.

다음 단계