다음을 통해 공유

Azure Functions에 대한 Azure IoT Hub 트리거

  • 아티클

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

설정 및 구성 세부 정보에 대한 자세한 내용은 개요를 참조하세요.

Important

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

함수 트리거를 사용하여 이벤트 허브 이벤트 스트림으로 전송된 이벤트에 응답합니다. 트리거를 설정하려면 기본 이벤트 허브에 대한 읽기 액세스 권한이 있어야 합니다. 함수가 트리거되면 함수에 전달된 메시지가 문자열로 입력됩니다.

사용량 및 프리미엄 플랜에 대한 Event Hubs 크기 조정 결정은 대상 기반 크기 조정을 통해 수행됩니다. 자세한 내용은 대상 기반 크기 조정을 참조하세요.

Azure Functions가 트리거를 사용하여 Event Hubs 이벤트 스트림으로 전송된 이벤트에 응답하는 방법에 대한 자세한 내용은 Azure에서 서버리스 함수와 Event Hubs 통합을 참조하세요.

Important

이 문서에서는 탭을 사용하여 여러 버전의 Node.js 프로그래밍 모델을 지원합니다. v4 모델은 일반적으로 사용 가능하며 JavaScript 및 TypeScript 개발자를 위해 보다 유연하고 직관적인 환경을 제공하도록 설계되었습니다. v4 모델의 작동 방식에 대한 자세한 내용은 Azure Functions Node.js 개발자 가이드를 참조하세요. v3과 v4의 차이점에 대해 자세히 알아보려면 마이그레이션 가이드를 참조하세요.

Azure Functions는 Python에 대해 두 가지 프로그래밍 모델을 지원합니다. 바인딩을 정의하는 방법은 선택한 프로그래밍 모델에 따라 달라집니다.

Python v2 프로그래밍 모델을 사용하면 Python 함수 코드에서 직접 데코레이터를 사용하여 바인딩을 정의할 수 있습니다. 자세한 내용은 Python 개발자 가이드를 참조하세요.

이 문서에서는 두 프로그래밍 모델을 모두 지원합니다.

예시

다음 예제는 설명 메시지 문자열이 로그에 기록되는 이벤트 허브를 기반으로 트리거되는 C# 함수를 보여 줍니다.

{
    private readonly ILogger<EventHubsFunction> _logger;

    public EventHubsFunction(ILogger<EventHubsFunction> logger)
    {
        _logger = logger;
    }

    [Function(nameof(EventHubFunction))]
    [FixedDelayRetry(5, "00:00:10")]
    [EventHubOutput("dest", Connection = "EventHubConnection")]
    public string EventHubFunction(
        [EventHubTrigger("src", Connection = "EventHubConnection")] string[] input,
        FunctionContext context)
    {
        _logger.LogInformation("First Event Hubs triggered message: {msg}", input[0]);

        var message = $"Output message created at {DateTime.Now}";
        return message;
    }

다음 예에서는 Event Hubs 트리거 TypeScript 함수를 보여 줍니다. 함수 는 이벤트 메타데이터 를 읽고 메시지를 기록합니다.

import { app, InvocationContext } from '@azure/functions';

export async function eventHubTrigger1(message: unknown, context: InvocationContext): Promise<void> {
    context.log('Event hub function processed message:', message);
    context.log('EnqueuedTimeUtc =', context.triggerMetadata.enqueuedTimeUtc);
    context.log('SequenceNumber =', context.triggerMetadata.sequenceNumber);
    context.log('Offset =', context.triggerMetadata.offset);
}

app.eventHub('eventHubTrigger1', {
    connection: 'myEventHubReadConnectionAppSetting',
    eventHubName: 'MyEventHub',
    cardinality: 'one',
    handler: eventHubTrigger1,
});

이벤트를 일괄 처리로 수신하려면 다음 예와 같이 cardinality를 many로 설정합니다.

import { app, InvocationContext } from '@azure/functions';

export async function eventHubTrigger1(messages: unknown[], context: InvocationContext): Promise<void> {
    context.log(`Event hub function processed ${messages.length} messages`);
    for (let i = 0; i < messages.length; i++) {
        context.log('Event hub message:', messages[i]);
        context.log(`EnqueuedTimeUtc = ${context.triggerMetadata.enqueuedTimeUtcArray[i]}`);
        context.log(`SequenceNumber = ${context.triggerMetadata.sequenceNumberArray[i]}`);
        context.log(`Offset = ${context.triggerMetadata.offsetArray[i]}`);
    }
}

app.eventHub('eventHubTrigger1', {
    connection: 'myEventHubReadConnectionAppSetting',
    eventHubName: 'MyEventHub',
    cardinality: 'many',
    handler: eventHubTrigger1,
});

다음 예에서는 Event Hubs 트리거 JavaScript 함수를 보여 줍니다. 함수 는 이벤트 메타데이터 를 읽고 메시지를 기록합니다.

const { app } = require('@azure/functions');

app.eventHub('eventHubTrigger1', {
    connection: 'myEventHubReadConnectionAppSetting',
    eventHubName: 'MyEventHub',
    cardinality: 'one',
    handler: (message, context) => {
        context.log('Event hub function processed message:', message);
        context.log('EnqueuedTimeUtc =', context.triggerMetadata.enqueuedTimeUtc);
        context.log('SequenceNumber =', context.triggerMetadata.sequenceNumber);
        context.log('Offset =', context.triggerMetadata.offset);
    },
});

이벤트를 일괄 처리로 수신하려면 다음 예와 같이 cardinality를 many로 설정합니다.

const { app } = require('@azure/functions');

app.eventHub('eventHubTrigger1', {
    connection: 'myEventHubReadConnectionAppSetting',
    eventHubName: 'MyEventHub',
    cardinality: 'many',
    handler: (messages, context) => {
        context.log(`Event hub function processed ${messages.length} messages`);
        for (let i = 0; i < messages.length; i++) {
            context.log('Event hub message:', messages[i]);
            context.log(`EnqueuedTimeUtc = ${context.triggerMetadata.enqueuedTimeUtcArray[i]}`);
            context.log(`SequenceNumber = ${context.triggerMetadata.sequenceNumberArray[i]}`);
            context.log(`Offset = ${context.triggerMetadata.offsetArray[i]}`);
        }
    },
});

PowerShell 코드는 다음과 같습니다.

param($eventHubMessages, $TriggerMetadata)

Write-Host "PowerShell eventhub trigger function called for message array: $eventHubMessages"

$eventHubMessages | ForEach-Object { Write-Host "Processed message: $_" }

다음 예제에서는 Event Hubs 트리거 바인딩 및 바인딩을 사용하는 Python 함수를 보여 줍니다. 함수 는 이벤트 메타데이터 를 읽고 메시지를 기록합니다. 이 예제는 v1 또는 v2 Python 프로그래밍 모델을 사용하는지 여부에 따라 달라집니다.

import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="EventHubTrigger1")
@app.event_hub_message_trigger(arg_name="myhub", 
                               event_hub_name="<EVENT_HUB_NAME>",
                               connection="<CONNECTION_SETTING>") 
def test_function(myhub: func.EventHubEvent):
    logging.info('Python EventHub trigger processed an event: %s',
                myhub.get_body().decode('utf-8'))

다음 예제에서는 Event Hubs 트리거의 메시지 본문을 기록하는 Event Hubs 트리거 바인딩을 보여 줍니다.

@FunctionName("ehprocessor")
public void eventHubProcessor(
  @EventHubTrigger(name = "msg",
                  eventHubName = "myeventhubname",
                  connection = "myconnvarname") String message,
       final ExecutionContext context )
       {
          context.getLogger().info(message);
 }

Java 함수 런타임 라이브러리에서 값이 이벤트 허브에서 가져온 매개 변수에 EventHubTrigger 주석을 사용합니다. 이러한 주석이 있는 매개 변수는 이벤트가 도착할 때 함수가 실행되도록 합니다. 이 주석은 을 사용하여 네이티브 Java 형식, POJO 또는 nullable 값과 함께 사용할 Optional<T>수 있습니다.

다음 예제에서는 날짜 계층 구조인 올바른 형식의 BlobOutput 경로를 제공하는 것과 함께 이벤트의 추가 검사를 위한 광범위한 SystemProperties 사용 및 기타 바인딩 옵션을 보여 줍니다.

package com.example;
import java.util.Map;
import java.time.ZonedDateTime;

import com.microsoft.azure.functions.annotation.*;
import com.microsoft.azure.functions.*;

/**
 * Azure Functions with Event Hub trigger.
 * and Blob Output using date in path along with message partition ID
 * and message sequence number from EventHub Trigger Properties
 */
public class EventHubReceiver {

    @FunctionName("EventHubReceiver")
    @StorageAccount("bloboutput")

    public void run(
            @EventHubTrigger(name = "message",
                eventHubName = "%eventhub%",
                consumerGroup = "%consumergroup%",
                connection = "eventhubconnection",
                cardinality = Cardinality.ONE)
            String message,

            final ExecutionContext context,

            @BindingName("Properties") Map<String, Object> properties,
            @BindingName("SystemProperties") Map<String, Object> systemProperties,
            @BindingName("PartitionContext") Map<String, Object> partitionContext,
            @BindingName("EnqueuedTimeUtc") Object enqueuedTimeUtc,

            @BlobOutput(
                name = "outputItem",
                path = "iotevents/{datetime:yy}/{datetime:MM}/{datetime:dd}/{datetime:HH}/" +
                       "{datetime:mm}/{PartitionContext.PartitionId}/{SystemProperties.SequenceNumber}.json")
            OutputBinding<String> outputItem) {

        var et = ZonedDateTime.parse(enqueuedTimeUtc + "Z"); // needed as the UTC time presented does not have a TZ
                                                             // indicator
        context.getLogger().info("Event hub message received: " + message + ", properties: " + properties);
        context.getLogger().info("Properties: " + properties);
        context.getLogger().info("System Properties: " + systemProperties);
        context.getLogger().info("partitionContext: " + partitionContext);
        context.getLogger().info("EnqueuedTimeUtc: " + et);

        outputItem.setValue(message);
    }
}

특성

In Process 및 격리된 작업자 프로세스 C# 라이브러리 모두 특성을 사용하여 트리거를 구성합니다. 대신 C# 스크립트는 C# 스크립팅 가이드에 설명된 대로 function.json 구성 파일을 사용합니다.

EventHubTriggerAttribute를 사용하여 다음 속성을 지원하는 이벤트 허브에서 트리거를 정의합니다.

매개 변수 설명
EventHubName 이벤트 허브의 이름입니다. 이벤트 허브 이름이 연결 문자열에 있는 경우 해당 값은 런타임 시 이 속성을 재정의합니다. %eventHubName%과 같이 앱 설정에서 참조할 수 있습니다.
ConsumerGroup 허브에서 이벤트를 구독하는 데 사용되는 소비자 그룹을 설정하는 선택적 속성입니다. 생략하면 $Default 소비자 그룹이 사용됩니다.
Connection Event Hubs에 연결하는 방법을 지정하는 앱 설정 또는 설정 컬렉션의 이름입니다. 자세한 내용은 연결을 참조하세요.

데코레이터

Python v2 프로그래밍 모델에만 적용됩니다.

데코레이터를 사용하여 정의된 Python v2 함수의 경우 다음 속성은 event_hub_message_trigger다음과 같습니다.

속성 설명
arg_name 함수 코드에서 이벤트 항목을 나타내는 변수의 이름입니다.
event_hub_name 이벤트 허브의 이름입니다. 이벤트 허브 이름이 연결 문자열에 있는 경우 해당 값은 런타임 시 이 속성을 재정의합니다.
connection Event Hubs에 연결하는 방법을 지정하는 앱 설정 또는 설정 컬렉션의 이름입니다. 연결을 참조하세요.

function.json 사용하여 정의된 Python 함수는 구성 섹션을 참조하세요.

주석

Java 함수 런타임 라이브러리에서 다음 설정을 지원하는 EventHubTrigger 주석을 사용합니다.

구성

Python v1 프로그래밍 모델에만 적용됩니다.

다음 표에서는 app.eventHub() 메서드에 전달된 options 개체에 설정할 수 있는 속성에 대해 설명합니다.

속성 설명
eventHubName 이벤트 허브의 이름입니다. 이벤트 허브 이름이 연결 문자열에 있는 경우 해당 값은 런타임 시 이 속성을 재정의합니다. %eventHubName% 앱 설정을 통해 참조할 수 있습니다.
consumerGroup 허브에서 이벤트를 구독하는 데 사용되는 소비자 그룹을 설정하는 선택적 속성입니다. 생략한 경우 $Default 소비자 그룹이 사용됩니다.
cardinality many로 설정하여 일괄 처리할 수 있도록 합니다. 생략하거나 설정 one하면 단일 메시지가 함수에 전달됩니다.
connection Event Hubs에 연결하는 방법을 지정하는 앱 설정 또는 설정 컬렉션의 이름입니다. 연결을 참조하세요.

다음 표에서는 런타임 버전에 따라 다른 function.json 파일에서 설정하는 트리거 구성 속성을 설명합니다.

function.json 속성 설명
type eventHubTrigger로 설정해야 합니다. 이 속성은 사용자가 Azure Portal에서 트리거를 만들 때 자동으로 설정됩니다.
direction in로 설정해야 합니다. 이 속성은 사용자가 Azure Portal에서 트리거를 만들 때 자동으로 설정됩니다.
이름 함수 코드에서 이벤트 항목을 나타내는 변수의 이름입니다.
eventHubName 이벤트 허브의 이름입니다. 이벤트 허브 이름이 연결 문자열에 있는 경우 해당 값은 런타임 시 이 속성을 재정의합니다. %eventHubName% 앱 설정을 통해 참조할 수 있습니다.
consumerGroup 허브에서 이벤트를 구독하는 데 사용되는 소비자 그룹을 설정하는 선택적 속성입니다. 생략한 경우 $Default 소비자 그룹이 사용됩니다.
cardinality many로 설정하여 일괄 처리할 수 있도록 합니다. 생략하거나 설정 one하면 단일 메시지가 함수에 전달됩니다.
connection Event Hubs에 연결하는 방법을 지정하는 앱 설정 또는 설정 컬렉션의 이름입니다. 연결을 참조하세요.

로컬에서 개발하는 경우 Values 컬렉션의 local.settings.json 파일에 애플리케이션 설정을 추가합니다.

사용

Event Hubs 트리거 및 IoT Hub 트리거 크기 조정 방법에 대해 자세히 알아보려면 Azure Functions로 이벤트 사용을 참조하세요.

Event Hubs 출력 바인딩에서 지원하는 매개 변수 형식은 Functions 런타임 버전, 확장 패키지 버전 및 사용된 C# 형식에 따라 다릅니다.

함수가 단일 이벤트를 처리하도록 하려는 경우 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 형식 바인딩에 대한 공통 종속성을 참조해야 합니다.

매개 변수 형식은 다음 중 하나일 수 있습니다.

  • int, String, byte[]와 같은 모든 네이티브 Java 형식.
  • 선택적 값을 사용하는 null 허용 값.
  • 모든 POJO 형식.

자세한 내용은 EventHubTrigger 참조를 확인합니다.

이벤트 메타데이터

Event Hubs 트리거는 몇 가지 메타데이터 속성을 제공합니다. 메타데이터 속성은 다른 바인딩에서 바인딩 식의 일부로 사용하거나 코드에서 매개 변수로 사용할 수 있습니다. 속성은 EventData 클래스에서 가져옵니다.

속성 Type 설명
PartitionContext PartitionContext PartitionContext 인스턴스입니다.
EnqueuedTimeUtc DateTime 큐에 담은 시간(UTC)입니다.
Offset string 이벤트 허브 파티션 스트림을 기준으로 데이터의 오프셋 오프셋은 Event Hubs 스트림 내의 이벤트에 대한 표식 또는 식별자입니다. 식별자는 Event Hubs 스트림의 파티션 내에서 고유합니다.
PartitionKey string 이벤트 데이터를 보내야 하는 파티션입니다.
Properties IDictionary<String,Object> 이벤트 데이터의 사용자 속성
SequenceNumber Int64 이벤트의 논리적 시퀀스 번호
SystemProperties IDictionary<String,Object> 이벤트 데이터를 포함한 시스템 속성입니다.

이 아티클의 앞부분에서 이러한 속성을 사용하는 코드 예제를 참조하세요.

연결

connection 속성은 연결 문자열을 포함하는 애플리케이션 설정의 이름을 포함하는 환경 구성에 대한 참조입니다. 이 연결 문자열은 네임스페이스에 대한 연결 정보 단추를 선택하여 얻을 수 있습니다. 연결 문자열은 이벤트 허브 자체가 아니라 Event Hubs 네임스페이스용이어야 합니다.

함수를 활성화하려면 연결 문자열에 최소한 "읽기" 권한이 있어야 합니다.

이 연결 문자열은 바인딩 구성의 connection 속성에 지정된 값과 일치하는 이름으로 애플리케이션 설정에 저장해야 합니다.

참고 항목

IoT Hub 트리거는 ID 기반 연결을 지원하지 않습니다. 관리 ID를 엔드투엔드로 사용해야 하는 경우 대신 IoT Hub 라우팅을 사용하여 제어하는 이벤트 허브에 데이터를 보낼 수 있습니다. 이러한 방식으로 아웃바운드 라우팅은 관리 ID로 인증될 수 있으며 이벤트는 관리 ID를 사용하여 해당 이벤트 허브에서 읽을 수 있습니다.

host.json 속성

host.json 파일에는 이벤트 허브 트리거 동작을 제어하는 설정이 포함되어 있습니다. 사용 가능한 설정에 대한 자세한 내용은 host.json 설정 섹션을 참조하세요.

다음 단계