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

  • 아티클

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

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

확장 설치

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

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

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

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

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

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

.NET CLI 사용:

dotnet add package Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues --version 5.0.0

참고 항목

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에서 직접 형식을 만들고 사용합니다.

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입니다.

다음 단계