Azure Functions의 Azure Event Hubs 트리거

이 문서에서는 Azure Functions에 Azure Event Hubs 트리거를 사용하는 방법에 대해 설명합니다. Azure Functions는 Event Hubs에 대한 트리거 및 출력 바인딩을 지원합니다.

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

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

예제

다음 예제에서는 Event Hubs 트리거의 메시지 본문을 기록하는 C# 함수를 보여줍니다.

[FunctionName("EventHubTriggerCSharp")]
public void Run([EventHubTrigger("samples-workitems", Connection = "EventHubConnectionAppSetting")] string myEventHubMessage, ILogger log)
{
    log.LogInformation($"C# function triggered to process a message: {myEventHubMessage}");
}

함수 코드에서 이벤트 메타데이터에 액세스하려면 EventData 개체에 바인딩합니다. 메서드 시그니처의 바인딩 식을 사용하여 동일한 속성에 액세스할 수도 있습니다. 다음 예제에서는 동일한 데이터를 가져오는 두 가지 방법을 모두 보여줍니다.

[FunctionName("EventHubTriggerCSharp")]
public void Run(
    [EventHubTrigger("samples-workitems", Connection = "EventHubConnectionAppSetting")] EventData myEventHubMessage,
    DateTime enqueuedTimeUtc,
    Int64 sequenceNumber,
    string offset,
    ILogger log)
{
    log.LogInformation($"Event: {Encoding.UTF8.GetString(myEventHubMessage.Body)}");
    // Metadata accessed by binding to EventData
    log.LogInformation($"EnqueuedTimeUtc={myEventHubMessage.SystemProperties.EnqueuedTimeUtc}");
    log.LogInformation($"SequenceNumber={myEventHubMessage.SystemProperties.SequenceNumber}");
    log.LogInformation($"Offset={myEventHubMessage.SystemProperties.Offset}");
    // Metadata accessed by using binding expressions in method parameters
    log.LogInformation($"EnqueuedTimeUtc={enqueuedTimeUtc}");
    log.LogInformation($"SequenceNumber={sequenceNumber}");
    log.LogInformation($"Offset={offset}");
}

일괄 처리에서 이벤트를 수신하려면 string 또는 EventData 배열을 만듭니다.

참고

일괄로 이벤트를 수신하면 DateTime enqueuedTimeUtc를 사용하여 위 예제와 같이 메서드 매개 변수에 바인딩할 수 없으며 각 EventData 개체에서 이러한 매개 변수를 수신해야 합니다.

[FunctionName("EventHubTriggerCSharp")]
public void Run([EventHubTrigger("samples-workitems", Connection = "EventHubConnectionAppSetting")] EventData[] eventHubMessages, ILogger log)
{
    foreach (var message in eventHubMessages)
    {
        log.LogInformation($"C# function triggered to process a message: {Encoding.UTF8.GetString(message.Body)}");
        log.LogInformation($"EnqueuedTimeUtc={message.SystemProperties.EnqueuedTimeUtc}");
    }
}

다음 예제에서는 function.json 파일의 Event Hubs 트리거 바인딩 및 바인딩을 사용하는 JavaScript 함수를 보여줍니다. 함수는 이벤트 메타데이터를 읽고 메시지를 기록합니다.

다음 예제에서는 function.json 파일의 Event Hubs 바인딩 데이터를 보여 줍니다. 이는 이후 버전과 비교하여 Functions 런타임 버전 1.x에서 다릅니다.

{
  "type": "eventHubTrigger",
  "name": "myEventHubMessage",
  "direction": "in",
  "eventHubName": "MyEventHub",
  "connection": "myEventHubReadConnectionAppSetting"
}

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

module.exports = function (context, myEventHubMessage) {
    context.log('Function triggered to process a message: ', myEventHubMessage);
    context.log('EnqueuedTimeUtc =', context.bindingData.enqueuedTimeUtc);
    context.log('SequenceNumber =', context.bindingData.sequenceNumber);
    context.log('Offset =', context.bindingData.offset);

    context.done();
};

일괄 처리에서 이벤트를 수신하려면 다음 예제에 표시된 대로 function.json 파일에서 cardinalitymany로 설정합니다.

{
  "type": "eventHubTrigger",
  "name": "eventHubMessages",
  "direction": "in",
  "eventHubName": "MyEventHub",
  "cardinality": "many",
  "connection": "myEventHubReadConnectionAppSetting"
}

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

module.exports = function (context, eventHubMessages) {
    context.log(`JavaScript eventhub trigger function called for message array ${eventHubMessages}`);

    eventHubMessages.forEach((message, index) => {
        context.log(`Processed message ${message}`);
        context.log(`EnqueuedTimeUtc = ${context.bindingData.enqueuedTimeUtcArray[index]}`);
        context.log(`SequenceNumber = ${context.bindingData.sequenceNumberArray[index]}`);
        context.log(`Offset = ${context.bindingData.offsetArray[index]}`);
    });

    context.done();
};

완전한 PowerShell 예제가 보류 중입니다.

다음 예제에서는 function.json 파일의 Event Hubs 트리거 바인딩 및 바인딩을 사용하는 Python 함수를 보여줍니다. 함수는 이벤트 메타데이터를 읽고 메시지를 기록합니다.

다음 예제에서는 function.json 파일에 있는 Event Hubs 데이터 바인딩을 표시합니다.

{
  "type": "eventHubTrigger",
  "name": "event",
  "direction": "in",
  "eventHubName": "MyEventHub",
  "connection": "myEventHubReadConnectionAppSetting"
}

다음은 Python 코드입니다.

import logging
import azure.functions as func


def main(event: func.EventHubEvent):
    logging.info(f'Function triggered to process a message: {event.get_body().decode()}')
    logging.info(f'  EnqueuedTimeUtc = {event.enqueued_time}')
    logging.info(f'  SequenceNumber = {event.sequence_number}')
    logging.info(f'  Offset = {event.offset}')

    # Metadata
    for key in event.metadata:
        logging.info(f'Metadata: {key} = {event.metadata[key]}')

다음 예제에서는 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 주석을 사용합니다. 이러한 주석을 사용하는 매개 변수로 인해 이벤트 도착 시 함수가 실행될 수 있습니다. Optional<T>을 사용하여 원시 Java 형식, POJO 또는 null 허용 값으로 이 주석을 사용할 수 있습니다.

다음 예제에서는 날짜 계층 구조인 올바른 형식의 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# 스크립트는 대신 function.json 구성 파일을 사용합니다.

C# 클래스 라이브러리에서 다음 특성을 지원하는 EventHubTriggerAttribute를 사용합니다.

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

주석

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

구성

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

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

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

사용량

Event Hubs 트리거 및 IoT Hub 트리거 확장 방식에 대한 자세한 내용은 Event Hubs 트리거를 참조하세요.

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

In Process C# 클래스 라이브러리 함수는 다음 형식을 지원합니다.

이 버전의 EventDataEventBody 대신 레거시 Body 형식에 대한 지원을 중단합니다.

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

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

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

이벤트 메타데이터

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

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

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

Connections

connection 속성은 앱이 Event Hubs에 연결되어야 하는 방법을 지정하는 환경 구성에 대한 참조입니다. 다음을 지정할 수 있습니다.

  • 연결 문자열이 포함된 애플리케이션 설정의 이름
  • 함께 ID 기반 연결을 정의하는 여러 애플리케이션 설정에 대한 공유 접두사의 이름입니다.

구성된 값이 단일 설정에 대해 정확히 일치하고 다른 설정에 대해 접두사가 일치하는 경우 정확한 일치가 사용됩니다.

연결 문자열

이벤트 허브 자체가 아닌 네임스페이스에 대한 연결 정보 단추를 클릭하여 이 연결 문자열을 가져옵니다. 연결 문자열은 이벤트 허브 자체가 아니라 Event Hubs 네임스페이스용이어야 합니다.

트리거에 사용될 때 연결 문자열은 함수를 활성화하기 위해 최소한 "읽기" 권한이 있어야 합니다. 출력 바인딩에 사용되는 경우 연결 문자열에는 이벤트 스트림에 메시지를 보낼 수 있는 "보내기" 권한이 있어야 합니다.

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

ID 기반 연결

버전 5.x 이상의 확장을 사용하는 경우 비밀이 있는 연결 문자열을 사용하는 대신 앱에서 Azure Active Directory ID를 사용하도록 할 수 있습니다. 이렇게 하려면 트리거 및 바인딩 구성의 connection 속성에 매핑되는 공통 접두사 아래에 설정을 정의합니다.

이 모드에서 확장에는 다음 속성이 필요합니다.

참고

사용량 요금제에서 작동하려면 현재 제공된 환경 변수에 AzureWebJobs 접두사가 있어야 합니다. 프리미엄 요금제에서는 이 접두사가 필요하지 않습니다.

속성 환경 변수 템플릿 설명 예제 값
정규화된 네임스페이스 AzureWebJobs<CONNECTION_NAME_PREFIX>__fullyQualifiedNamespace 정규화된 Event Hubs 네임스페이스입니다. <event_hubs_namespace>.servicebus.windows.net

연결을 사용자 지정하기 위해 추가 속성을 설정할 수 있습니다. ID 기반 연결의 공통 속성을 참조하세요.

참고

Azure App Configuration 또는 Key Vault를 사용하여 관리 ID 연결에 대한 설정을 제공하는 경우 설정 이름은 올바르게 확인되도록 __ 대신 : 또는 /와 같은 유효한 키 구분 기호를 사용해야 합니다.

예: <CONNECTION_NAME_PREFIX>:fullyQualifiedNamespace.

Azure Functions 서비스에서 호스트되는 경우 ID 기반 연결에 관리 ID가 사용됩니다. 사용자가 할당한 ID는 credentialclientID 속성을 사용하여 지정할 수 있지만 기본적으로 시스템 할당 ID가 사용됩니다. 리소스 ID를 사용하여 사용자가 할당한 ID를 구성하는 것은 지원되지 않습니다. 로컬 개발과 같은 다른 컨텍스트에서 실행할 때 사용자 지정할 수 있지만 대신 개발자 ID가 사용됩니다. ID 기반 연결을 사용하여 로컬 개발을 참조하세요.

ID에 권한 부여

사용되는 모든 ID에는 의도한 작업을 수행할 수 있는 권한이 있어야 합니다. 이러한 권한을 제공하는 기본 제공 또는 사용자 지정 역할을 사용하여 Azure RBAC에서 역할을 할당해야 합니다.

중요

일부 사용 권한은 모든 컨텍스트에 필요하지 않은 대상 서비스에 의해 노출될 수 있습니다. 가능한 경우 최소 권한 원칙을 준수하여 ID에 필요한 권한만 부여하세요. 예를 들어 앱이 데이터 원본에서 읽을 수만 있으면 되는 경우 읽기 권한만 있는 역할을 사용합니다. 읽기 작업에 대한 과도한 권한이 될 수 있으므로 해당 서비스에 쓰기도 허용하는 역할을 할당하는 것은 부적절합니다. 마찬가지로 역할 할당이 읽어야 하는 리소스에 대해서만 범위가 할당되도록 할 수 있습니다.

런타임에 이벤트 허브에 대한 액세스를 제공하는 역할 할당을 만들어야 합니다. 역할 할당의 범위는 이벤트 허브 자체가 아니라 Event Hubs 네임스페이스에 대한 것이어야 합니다. 소유자와 같은 관리 역할로는 충분하지 않습니다. 다음 표는 정상 작동에서 Event Hubs 확장을 사용할 때 권장되는 기본 제공 역할을 보여 줍니다. 작성하는 코드에 따라 애플리케이션에 추가 권한이 필요할 수 있습니다.

바인딩 유형 기본 제공 역할 예
트리거 Azure Event Hubs 데이터 수신기, Azure Event Hubs 데이터 소유자
출력 바인딩 Azure Event Hubs 데이터 보내는 사람

host.json 설정

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

다음 단계