다음을 통해 공유

Azure Functions에 대한 Azure Queue Storage 트리거 및 바인딩 개요

  • 아티클

Azure Functions는 새 Azure Queue Storage 메시지가 생성되면 실행할 수 있으며 함수 내에서 큐 메시지를 작성할 수 있습니다.

작업 Type
큐 스토리지 데이터 변경으로 함수 실행 트리거
큐 스토리지 메시지 쓰기 출력 바인딩

확장 설치

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

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

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

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

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

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

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

.NET CLI 사용:

dotnet add package Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues

참고 항목

Azure Blob, Azure Queues 및 Azure Tables는 이제 별도의 확장을 사용하고 개별적으로 참조됩니다. 예를 들어 .NET 격리된 프로세스 앱의 세 가지 서비스 모두에 대해 트리거와 바인딩을 사용하려면 프로젝트에 다음 패키지를 추가해야 합니다.

이전에는 확장이 Microsoft.Azure.Functions.Worker.Extensions.Storage, 버전 4.x로 함께 제공되었습니다. 이 동일한 패키지에는 Blob 및 큐에 대해서만 분할 패키지를 참조하는 5.x 버전도 있습니다. 따라서 이전 버전에서 패키지 참조를 업그레이드할 때 새로운 Microsoft.Azure.Functions.Worker.Extensions.Tables NuGet 패키지를 추가로 참조해야 할 수 있습니다. 또한 이러한 새로운 분할 패키지를 참조할 때 결합된 스토리지 패키지의 이전 버전을 참조하고 있지 않은지 확인합니다. 이렇게 하면 동일한 바인딩의 두 정의에서 충돌이 발생하기 때문입니다.

번들 설치

Blob Storage 바인딩은 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.Storage.Queues의 형식에 대한 바인딩 지원은 미리 보기 상태입니다.

큐 트리거

큐 트리거는 다음 형식에 바인딩할 수 있습니다.

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

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

큐 출력 바인딩

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

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

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

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

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

host.json 설정

이 섹션에서는 버전 2.x 이상에서 이 바인딩에 사용할 수 있는 구성 설정에 대해 설명합니다. host.json 파일의 설정은 함수 앱 인스턴스의 모든 함수에 적용됩니다. 아래 예제 host.json 파일에는 이 바인딩에 대한 버전 2.x 이상 설정만 포함되어 있습니다. 버전 2.x 이상 버전의 함수 앱 구성 설정에 대한 자세한 내용은 Azure Functions용 host.json 참조를 참조하세요.

참고 항목

Functions 1.x에서 host.json의 참조는 Azure Functions 1.x에 대한 host.json 참조를 참조하세요.

{
    "version": "2.0",
    "extensions": {
        "queues": {
            "maxPollingInterval": "00:00:02",
            "visibilityTimeout" : "00:00:30",
            "batchSize": 16,
            "maxDequeueCount": 5,
            "newBatchThreshold": 8,
            "messageEncoding": "base64"
        }
    }
}
속성 기본값 설명
maxPollingInterval 00:01:00 큐 폴링 간의 최대 간격입니다. 최소 간격은 00:00:00.100(100ms)입니다. 간격이 maxPollingInterval까지 점진적으로 증가합니다. 기본값 maxPollingInterval 은 00:01:00(1분)입니다. maxPollingInterval 는 00:00:00.100(100ms) 미만이어야 합니다. Functions 2.x 이상에서 데이터 형식은 TimeSpan입니다. Functions 1.x에서는 밀리초 단위입니다.
visibilityTimeout 00:00:00 메시지 처리가 실패하는 경우 재시도 사이의 간격입니다.
batchSize 16 함수 런타임이 동시에 검색하고 병렬로 처리하는 큐 메시지 수입니다. 처리되는 개수가 newBatchThreshold로 감소하면 런타임은 다른 일괄 처리를 가져와 해당 메시지의 처리를 시작합니다. 따라서 함수당 처리되는 최대 동시 메시지 수는 batchSize + newBatchThreshold입니다. 이 제한은 큐 트리거 함수에 개별적으로 적용됩니다.

하나의 큐에 수신된 메시지에 대해 병렬 실행을 방지하려면 batchSize을 1로 설정합니다. 그러나 이 설정은 함수 앱이 단일 VM(가상 머신)에서 실행되는 동안에만 동시성을 제거합니다. 함수 앱이 여러 VM에 확장되면 각 VM은 각 큐 트리거 함수의 인스턴스 하나를 실행할 수 있습니다.

최대 batchSize은 32입니다.
maxDequeueCount 5 포이즌 큐로 이동하기 전에 메시지 처리를 시도할 횟수입니다.
newBatchThreshold N*batchSize/2 동시에 처리되는 메시지의 수가 이 숫자로 내려갈 때마다 런타임은 다른 일괄 처리를 검색합니다.

N 는 App Service 또는 Premium Plans에서 실행할 때 사용할 수 있는 vCPU 수를 나타냅니다. 해당 값은 1 소비 계획에 대한 것입니다.
messageEncoding base64 이 설정은 확장 번들 버전 5.0.0 이상에서만 사용할 수 있습니다. 메시지의 인코딩 형식을 나타냅니다. 유효한 값은 base64 및 none입니다.

다음 단계