Azure Functions에 대 한 Azure Service Bus 출력 바인딩Azure Service Bus output binding for Azure Functions

Azure Service Bus 출력 바인딩을 사용하여 큐 또는 토픽 메시지를 보냅니다.Use Azure Service Bus output binding to send queue or topic messages.

설정 및 구성 세부 정보에 관한 내용은 개요를 참조하세요.For information on setup and configuration details, see the overview.

예제Example

다음 예제에서는 Service Bus 큐 메시지를 보내는 C# 함수를 보여줍니다.The following example shows a C# function that sends a Service Bus queue message:

[FunctionName("ServiceBusOutput")]
[return: ServiceBus("myqueue", Connection = "ServiceBusConnection")]
public static string ServiceBusOutput([HttpTrigger] dynamic input, ILogger log)
{
    log.LogInformation($"C# function processed: {input.Text}");
    return input.Text;
}

특성 및 주석Attributes and annotations

C# 클래스 라이브러리에서 ServiceBusAttribute를 사용합니다.In C# class libraries, use the ServiceBusAttribute.

특성의 생성자는 큐의 이름 또는 토픽과 구독을 사용합니다.The attribute's constructor takes the name of the queue or the topic and subscription. 연결의 액세스 권한을 지정할 수도 있습니다.You can also specify the connection's access rights. 액세스 권한을 설정을 선택하는 방법은 출력 - 구성 섹션에서 설명합니다.How to choose the access rights setting is explained in the Output - configuration section. 함수의 반환 값에 적용된 특성을 보여주는 예제는 다음과 같습니다.Here's an example that shows the attribute applied to the return value of the function:

[FunctionName("ServiceBusOutput")]
[return: ServiceBus("myqueue")]
public static string Run([HttpTrigger] dynamic input, ILogger log)
{
    ...
}

Connection다음 예제와 같이 사용할 Service Bus 연결 문자열을 포함 하는 앱 설정의 이름을 지정 하도록 속성을 설정할 수 있습니다.You can set the Connection property to specify the name of an app setting that contains the Service Bus connection string to use, as shown in the following example:

[FunctionName("ServiceBusOutput")]
[return: ServiceBus("myqueue", Connection = "ServiceBusConnection")]
public static string Run([HttpTrigger] dynamic input, ILogger log)
{
    ...
}

전체 예제는 출력-예제를 참조 하세요.For a complete example, see Output - example.

ServiceBusAccount 특성을 사용하여 클래스, 메서드 또는 매개 변수 수준에서 사용할 Service Bus 계정을 지정합니다.You can use the ServiceBusAccount attribute to specify the Service Bus account to use at class, method, or parameter level. 자세한 내용은 트리거 - 특성을 참조하세요.For more information, see Trigger - attributes.

구성Configuration

다음 표에서는 function.json 파일 및 ServiceBus 특성에 설정된 바인딩 구성 속성을 설명합니다.The following table explains the binding configuration properties that you set in the function.json file and the ServiceBus attribute.

function.json 속성function.json property 특성 속성Attribute property DescriptionDescription
typetype 해당 없음n/a "serviceBus"로 설정해야 합니다.Must be set to "serviceBus". 이 속성은 사용자가 Azure Portal에서 트리거를 만들 때 자동으로 설정됩니다.This property is set automatically when you create the trigger in the Azure portal.
directiondirection 해당 없음n/a "out"으로 설정해야 합니다.Must be set to "out". 이 속성은 사용자가 Azure Portal에서 트리거를 만들 때 자동으로 설정됩니다.This property is set automatically when you create the trigger in the Azure portal.
namename 해당 없음n/a 함수 코드에서 큐 또는 토픽 메시지를 나타내는 변수의 이름입니다.The name of the variable that represents the queue or topic message in function code. "$return"으로 설정하여 함수 반환 값을 참조합니다.Set to "$return" to reference the function return value.
queueNamequeueName QueueNameQueueName 큐의 이름입니다.Name of the queue. 토픽이 아닌 큐 메시지를 보내는 경우에만 설정합니다.Set only if sending queue messages, not for a topic.
topicNametopicName TopicNameTopicName 항목의 이름입니다.Name of the topic. 큐가 아닌 토픽 메시지를 보내는 경우에만 설정합니다.Set only if sending topic messages, not for a queue.
connectionconnection 연결Connection 이 바인딩에 사용할 Service Bus 연결 문자열을 포함하는 앱 설정의 이름입니다.The name of an app setting that contains the Service Bus connection string to use for this binding. 앱 설정 이름이 "AzureWebJobs"로 시작하는 경우 이름의 나머지만을 지정할 수 있습니다.If the app setting name begins with "AzureWebJobs", you can specify only the remainder of the name. 예를 들어을 connection "MyServiceBus"로 설정 하는 경우 함수 런타임은 이름이 "AzureWebJobsMyServiceBus" 인 앱 설정을 찾습니다.For example, if you set connection to "MyServiceBus", the Functions runtime looks for an app setting that is named "AzureWebJobsMyServiceBus". connection을 비워 두면 함수 런타임 기능은 "AzureWebJobsServiceBus"라는 앱 설정에서 기본 Service Bus 연결 문자열을 사용합니다.If you leave connection empty, the Functions runtime uses the default Service Bus connection string in the app setting that is named "AzureWebJobsServiceBus".

연결 문자열을 얻으려면 관리 자격 증명 가져오기에 나온 단계를 따릅니다.To obtain a connection string, follow the steps shown at Get the management credentials. 연결 문자열은 Service Bus 네임스페이스에 대한 것이어야 하며, 특정 큐 또는 항목으로 제한되지 않습니다.The connection string must be for a Service Bus namespace, not limited to a specific queue or topic.
accessRights (v1에만 해당)accessRights (v1 only) AccessAccess 연결 문자열에 대한 액세스 권한입니다.Access rights for the connection string. 사용 가능한 값은 managelisten입니다.Available values are manage and listen. 기본값은 manage이며, connection관리 권한이 있음을 의미합니다.The default is manage, which indicates that the connection has the Manage permission. 관리 권한이 없는 연결 문자열을 사용하는 경우 accessRights을 "listen"으로 설정합니다.If you use a connection string that does not have the Manage permission, set accessRights to "listen". 그렇지 않으면 함수 런타임은 관리 권한이 필요한 작업 시도를 실패할 수 있습니다.Otherwise, the Functions runtime might fail trying to do operations that require manage rights. Azure Functions 버전 2.x 이상에서는 Service Bus SDK의 최신 버전이 관리 작업을 지원 하지 않으므로이 속성을 사용할 수 없습니다.In Azure Functions version 2.x and higher, this property is not available because the latest version of the Service Bus SDK doesn't support manage operations.

로컬로 개발하는 경우 앱 설정은 local.settings.json 파일로 이동합니다.When you're developing locally, app settings go into the local.settings.json file.

사용량Usage

Azure Functions 1.x에서 큐가 존재하지 않고 accessRightsmanage로 설정한 경우 런타임은 큐를 만듭니다.In Azure Functions 1.x, the runtime creates the queue if it doesn't exist and you have set accessRights to manage. 함수 버전 2.x 이상에서는 큐 또는 항목이 이미 존재 해야 합니다. 존재 하지 않는 큐 또는 토픽을 지정 하면 함수가 실패 합니다.In Functions version 2.x and higher, the queue or topic must already exist; if you specify a queue or topic that doesn't exist, the function will fail.

출력 바인딩에 대해 다음 매개 변수 형식을 사용 합니다.Use the following parameter types for the output binding:

  • out T paramName - T는 JSON 직렬화 가능 형식일 수 있습니다.out T paramName - T can be any JSON-serializable type. 함수가 종료될 때 매개 변수 값이 null이면 함수는 null 개체와 메시지를 만듭니다.If the parameter value is null when the function exits, Functions creates the message with a null object.
  • out string - 함수가 종료될 때 매개 변수 값이 null인 경우 함수는 메시지를 만들지 않습니다.out string - If the parameter value is null when the function exits, Functions does not create a message.
  • out byte[] - 함수가 종료될 때 매개 변수 값이 null인 경우 함수는 메시지를 만들지 않습니다.out byte[] - If the parameter value is null when the function exits, Functions does not create a message.
  • out BrokeredMessage -함수가 종료 될 때 매개 변수 값이 null 이면 함수는 (함수 1. x의 경우) 메시지를 만들지 않습니다.out BrokeredMessage - If the parameter value is null when the function exits, Functions does not create a message (for Functions 1.x)
  • out Message -함수가 종료 될 때 매개 변수 값이 null 이면 함수가 메시지를 만들지 않습니다 (함수 2.x 이상).out Message - If the parameter value is null when the function exits, Functions does not create a message (for Functions 2.x and higher)
  • ICollector<T> 또는 IAsyncCollector<T> (비동기 메서드의 경우)-여러 메시지를 만드는 데 사용할입니다.ICollector<T> or IAsyncCollector<T> (for async methods) - For creating multiple messages. 메시지는 Add 메서드를 호출할 때 생성됩니다.A message is created when you call the Add method.

C # 함수를 사용 하는 경우:When working with C# functions:

  • 비동기 함수에는 매개 변수 대신 반환 값이 필요 IAsyncCollector out 합니다.Async functions need a return value or IAsyncCollector instead of an out parameter.

  • 세션 ID에 액세스 하려면 형식에 바인딩하고 Message 속성을 사용 합니다 sessionId .To access the session ID, bind to a Message type and use the sessionId property.

예외 및 반환 코드Exceptions and return codes

바인딩Binding 참고Reference
Service BusService Bus Service Bus 오류 코드Service Bus Error Codes
Service BusService Bus Service Bus 한도Service Bus Limits

host.json 설정host.json settings

이 섹션에서는 버전 2.x 이상에서이 바인딩에 사용할 수 있는 전역 구성 설정에 대해 설명 합니다.This section describes the global configuration settings available for this binding in versions 2.x and higher. 아래 파일에 host.js예제에는이 바인딩에 대 한 설정만 포함 되어 있습니다.The example host.json file below contains only the settings for this binding. 전역 구성 설정에 대 한 자세한 내용은 Azure Functions 버전에 대 한 참조host.js를 참조 하세요.For more information about global configuration settings, see host.json reference for Azure Functions version.

참고

Functions 1.x에서 host.json의 참조는 Azure Functions 1.x에 대한 host.json 참조를 참조하세요.For a reference of host.json in Functions 1.x, see host.json reference for Azure Functions 1.x.

{
    "version": "2.0",
    "extensions": {
        "serviceBus": {
            "prefetchCount": 100,
            "messageHandlerOptions": {
                "autoComplete": true,
                "maxConcurrentCalls": 32,
                "maxAutoRenewDuration": "00:05:00"
            },
            "sessionHandlerOptions": {
                "autoComplete": false,
                "messageWaitTimeout": "00:00:30",
                "maxAutoRenewDuration": "00:55:00",
                "maxConcurrentSessions": 16
            }
        }
    }
}

isSessionsEnabled을로 설정한 경우 true 이 적용 됩니다 sessionHandlerOptions .If you have isSessionsEnabled set to true, the sessionHandlerOptions will be honored. isSessionsEnabled을로 설정한 경우 false 이 적용 됩니다 messageHandlerOptions .If you have isSessionsEnabled set to false, the messageHandlerOptions will be honored.

속성Property 기본값Default DescriptionDescription
prefetchCountprefetchCount 00 메시지 수신자가 동시에 요청할 수 있는 메시지 수를 가져오거나 설정 합니다.Gets or sets the number of messages that the message receiver can simultaneously request.
maxAutoRenewDurationmaxAutoRenewDuration 00:05:0000:05:00 메시지 잠금이 자동으로 갱신되는 최대 기간입니다.The maximum duration within which the message lock will be renewed automatically.
autoCompleteautoComplete truetrue 트리거가 처리 후 자동으로 완료를 호출 해야 하는지, 아니면 함수 코드가 수동으로 complete를 호출 하는지 여부입니다.Whether the trigger should automatically call complete after processing, or if the function code will manually call complete.

을로 설정 하 false 는 것은 c # 에서만 지원 됩니다.Setting to false is only supported in C#.

로 설정 true 된 경우 함수 실행이 성공적으로 완료 되 면 트리거가 자동으로 메시지를 완료 하 고, 그렇지 않으면 메시지를 무시 합니다.If set to true, the trigger completes the message automatically if the function execution completes successfully, and abandons the message otherwise.

로 설정 하면 false MessageReceiver 메서드를 호출 하 여 메시지를 완료 하거나 중단 하거나 배달 못한 편지를 배달 해야 합니다.When set to false, you are responsible for calling MessageReceiver methods to complete, abandon, or deadletter the message. 예외를 throw 하 고 메서드를 호출 하지 않은 경우에 MessageReceiver 는 잠금이 유지 됩니다.If an exception is thrown (and none of the MessageReceiver methods are called), then the lock remains. 잠금이 만료 되 면 메시지는 증가 된로 다시 큐에 대기 되며 DeliveryCount 잠금이 자동으로 갱신 됩니다.Once the lock expires, the message is re-queued with the DeliveryCount incremented and the lock is automatically renewed.

비 C # 함수에서 함수의 예외는 백그라운드에서 런타임 호출을 발생 합니다 abandonAsync .In non-C# functions, exceptions in the function results in the runtime calls abandonAsync in the background. 예외가 발생 하지 않으면 completeAsync 가 백그라운드에서 호출 됩니다.If no exception occurs, then completeAsync is called in the background.
maxConcurrentCallsmaxConcurrentCalls 1616 메시지 펌프가 확장 인스턴스당 시작 해야 하는 콜백에 대 한 최대 동시 호출 수입니다.The maximum number of concurrent calls to the callback that the message pump should initiate per scaled instance. 기본적으로 함수 런타임은 여러 개의 메시지를 동시에 처리합니다.By default, the Functions runtime processes multiple messages concurrently.
maxConcurrentSessionsmaxConcurrentSessions 20002000 크기 조정 된 인스턴스당 동시에 처리할 수 있는 최대 세션 수입니다.The maximum number of sessions that can be handled concurrently per scaled instance.

다음 단계Next steps