다음을 통해 공유

Azure Functions에 대한 Azure Service Bus 바인딩

  • 아티클

Azure Functions는 트리거 및 바인딩을 통해 Azure Service Bus와 통합됩니다. Service Bus와 통합하면 큐 또는 토픽 메시지에 반응하고 보내는 함수를 빌드할 수 있습니다.

작업 Type
Service Bus 큐 또는 토픽 메시지를 만들 때 함수 실행 트리거
Azure Service Bus 메시지 보내기 출력 바인딩

확장 설치

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

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

이 NuGet 패키지를 설치하는 프로젝트에 확장을 추가합니다.

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

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

이 버전을 사용하면 Azure.Messaging.ServiceBus의 형식에 바인딩할 수 있습니다.

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

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

번들 설치

Service Bus 바인딩은 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# 함수는 런타임에서 격리된 프로세스에서 실행됩니다.

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

격리된 작업자 프로세스는 아래 표에 따라 매개 변수 형식을 지원합니다.

Service Bus 트리거

함수가 단일 메시지를 처리하도록 하려면 Service Bus 트리거가 다음 형식에 바인딩할 수 있습니다.

Type 설명
string 문자열 메시지입니다. 메시지가 간단한 텍스트일 때 사용합니다.
byte[] 메시지의 바이트입니다.
JSON 직렬화 가능 형식 이벤트에 JSON 데이터가 포함된 경우 Functions는 JSON 데이터를 POCO(일반 CLR 개체) 형식으로 역직렬화하려고 합니다.
ServiceBusReceivedMessage1 메시지 개체입니다.

바인딩할 ServiceBusReceivedMessage때 필요에 따라 ServiceBusMessageActions1,2 형식의 매개 변수를 포함하여 메시지 결제 작업을 수행할 수도 있습니다.

함수가 메시지 일괄 처리를 처리하도록 하려면 Service Bus 트리거가 다음 형식에 바인딩할 수 있습니다.

Type 설명
T[] 여기서 T는 단일 메시지 유형 중 하나입니다. 일괄 처리의 이벤트 배열입니다. 각 항목은 하나의 이벤트를 나타냅니다.

바인딩할 ServiceBusReceivedMessage[]때 필요에 따라 ServiceBusMessageActions1,2 형식의 매개 변수를 포함하여 메시지 결제 작업을 수행할 수도 있습니다.

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

2 사용할 ServiceBusMessageActions때 트리거 특성 false 의 AutoCompleteMessages 속성을 .로 설정합니다. 이렇게 하면 함수 호출이 성공한 후 런타임에서 메시지를 완료하지 못하게 됩니다.

Service Bus 출력 바인딩

함수가 단일 메시지를 작성하도록 하려는 경우 Service Bus 출력 바인딩은 다음 형식에 바인딩될 수 있습니다.

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

함수가 여러 메시지를 쓰도록 하려는 경우 Service Bus 출력 바인딩을 다음 형식에 바인딩할 수 있습니다.

Type 설명
T[] 여기서 T는 단일 메시지 유형 중 하나입니다. 여러 메시지를 포함하는 배열입니다. 각 항목은 하나의 메시지를 나타냅니다.

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

host.json 설정

이 섹션에서는 런타임 및 확장 버전에 따라 달라지는 이 바인딩에 사용할 수 있는 구성 설정에 대해 설명합니다.

{
    "version": "2.0",
    "extensions": {
        "serviceBus": {
            "clientRetryOptions":{
                "mode": "exponential",
                "tryTimeout": "00:01:00",
                "delay": "00:00:00.80",
                "maxDelay": "00:01:00",
                "maxRetries": 3
            },
            "prefetchCount": 0,
            "transportType": "amqpWebSockets",
            "webProxy": "https://proxyserver:8080",
            "autoCompleteMessages": true,
            "maxAutoLockRenewalDuration": "00:05:00",
            "maxConcurrentCalls": 16,
            "maxConcurrentSessions": 8,
            "maxMessageBatchSize": 1000,
            "minMessageBatchSize": 1,
            "maxBatchWaitTime": "00:00:30",
            "sessionIdleTimeout": "00:01:00",
            "enableCrossEntityTransactions": false
        }
    }
}

clientRetryOptions 설정은 Service Bus 서비스와의 상호 작용에만 적용됩니다. 함수 실행 다시 시도에는 영향을 주지 않습니다. 자세한 내용은 다시 시도를 참조하세요.

속성 기본값 설명
mode Exponential 다시 시도 지연을 계산하는 데 사용하는 방법입니다. 기본 지수 모드는 각 시도가 다시 시도하기 전에 대기 시간을 늘리는 백오프 전략을 기반으로 지연된 시도를 다시 시도합니다. Fixed 모드는 고정된 간격으로 시도를 다시 시도하며 각 지연은 지속 시간이 일정합니다.
tryTimeout 00:01:00 시도당 작업을 대기할 최대 기간입니다.
delay 00:00:00.80 재시도 사이에 적용할 지연 또는 백오프 요소입니다.
maxDelay 00:01:00 재시도 사이에 허용되는 최대 지연 시간
maxRetries 3 연결된 작업이 실패한 것으로 간주하기 전 최대 다시 시도 횟수입니다.
prefetchCount 0 메시지 수신자가 동시에 요청할 수 있는 메시지 수를 가져오거나 설정합니다.
transportType amqpTcp Service Bus와 통신하는 데 사용되는 프로토콜 및 전송입니다. 사용 가능한 옵션: amqpTcp, amqpWebSockets
webProxy 해당 없음 웹 소켓을 통해 Service Bus와 통신하는 데 사용할 프록시입니다. 프록시는 amqpTcp 전송과 함께 사용할 수 없습니다.
autoCompleteMessages true 함수를 성공적으로 실행한 후 메시지를 자동으로 완료할지 여부를 결정합니다.
maxAutoLockRenewalDuration 00:05:00 메시지 잠금이 자동으로 갱신되는 최대 기간입니다. 이 설정은 한 번에 하나의 메시지를 수신하는 함수에만 적용됩니다.
maxConcurrentCalls 16 확장된 인스턴스당 시작되어야 하는 콜백에 대한 최대 동시 호출 수입니다. 기본적으로 함수 런타임은 여러 개의 메시지를 동시에 처리합니다. 이 설정은 트리거의 isSessionsEnabled 속성 또는 특성이 로 설정된 false경우에만 사용됩니다. 이 설정은 한 번에 하나의 메시지를 수신하는 함수에만 적용됩니다.
maxConcurrentSessions 8 크기 조정된 인스턴스당 동시에 처리할 수 있는 최대 세션 수입니다. 이 설정은 트리거의 isSessionsEnabled 속성 또는 특성이 로 설정된 true경우에만 사용됩니다. 이 설정은 한 번에 하나의 메시지를 수신하는 함수에만 적용됩니다.
maxMessageBatchSize 1000 각 함수 호출에 전달될 최대 메시지 수입니다. 이 설정은 일괄 처리 메시지를 수신하는 함수에만 적용됩니다.
minMessageBatchSize1 1 일괄 처리에서 원하는 최소 메시지 수입니다. 최소값은 함수가 여러 메시지를 수신하고 maxMessageBatchSize보다 작아야 하는 경우에만 적용됩니다.
최소 크기는 엄격하게 보장되지 않습니다. maxBatchWaitTime가 경과하기 전에전체 일괄 처리를 준비할 수 없는 경우 부분 일괄 처리가 디스패치됩니다.
maxBatchWaitTime1 00:00:30 함수를 호출하기 전에 트리거가 일괄 처리를 채우기 위해 대기해야 하는 최대 간격입니다. 대기 시간은 minMessageBatchSize이(가) 1보다 크고 그렇지 않으면 무시되는 경우에만 고려 됩니다. 대기 시간이 경과하기 전에 minMessageBatchSize 메시지보다 적게 사용할 수 있는 경우 함수는 부분 일괄 처리로 호출됩니다. 허용되는 가장 긴 대기 시간은 엔터티 메시지 잠금 기간의 50%입니다. 즉, 허용되는 최대 시간은 2분 30초입니다. 그렇지 않으면 잠금 예외가 발생할 수 있습니다.

참고: 이 간격은 함수가 호출되는 정확한 타이밍에 대한 엄격한 보장이 아닙니다. 타이머 정밀도로 인해 오차 범위가 작습니다.
sessionIdleTimeout 해당 없음 현재 활성 세션에 대해 메시지가 수신될 때까지 대기할 최대 시간입니다. 이 시간이 경과하면 세션이 닫히고 함수가 다른 세션을 처리하려고 시도합니다.
enableCrossEntityTransactions false Service Bus 네임스페이스의 여러 엔터티에 걸쳐 있는 트랜잭션을 사용하도록 설정할지 여부를 나타냅니다.

1minMessageBatchSize 및 maxBatchWaitTime을(를) 사용하려면 패키지Microsoft.Azure.WebJobs.Extensions.ServiceBus의 v5.10.0 이상 버전이 필요합니다.

다음 단계