Привязки служебной шины Azure для службы "Функции Azure"Azure Service Bus bindings for Azure Functions

В этой статье описывается использование привязок служебной шины Azure в службе "Функции Azure".This article explains how to work with Azure Service Bus bindings in Azure Functions. Функции Azure поддерживают привязки триггера и выходные привязки для очередей и разделов служебной шины.Azure Functions supports trigger and output bindings for Service Bus queues and topics.

Это справочные сведения для разработчиков функций Azure.This is reference information for Azure Functions developers. Если вы новичок в функциях Azure, начните со следующих ресурсов:If you're new to Azure Functions, start with the following resources:

Пакеты – Функции 1.xPackages - Functions 1.x

Привязки служебной шины доступны в пакете NuGet Microsoft.Azure.WebJobs.ServiceBus версии 2.х.The Service Bus bindings are provided in the Microsoft.Azure.WebJobs.ServiceBus NuGet package, version 2.x.

В следующей таблице указано как добавить поддержку для этой привязки в каждой среде разработки.The following table tells how to add support for this binding in each development environment.

Среда разработкиDevelopment environment Для добавления поддержки вTo add support in
Функции 1.xFunctions 1.x
Локальная разработка – библиотека классов C#Local development - C# class library Установка пакетаInstall the package
Локальная разработка – Скрипт C#, JavaScript, F#Local development - C# script, JavaScript, F# АвтоматическийAutomatic
Разработка на порталеPortal development АвтоматическийAutomatic

Packages — функции 2. x и более поздних версийPackages - Functions 2.x and higher

Привязки служебной шины доступны в пакете NuGet Microsoft.Azure.WebJobs.Extensions.ServiceBus версии 3.х.The Service Bus bindings are provided in the Microsoft.Azure.WebJobs.Extensions.ServiceBus NuGet package, version 3.x. Исходный код для пакета находится в репозитории GitHub Azure-functions-servicebus-Extension .Source code for the package is in the azure-functions-servicebus-extension GitHub repository.

Примечание

Версии 2. x и выше не создают раздел или подписку, настроенные в экземпляре ServiceBusTrigger.Versions 2.x and higher do not create the topic or subscription configured in the ServiceBusTrigger instance. Эти версии основаны на Microsoft. Azure. servicebus , который не обрабатывает управление очередями.These versions are based on Microsoft.Azure.ServiceBus which doesn’t handle queue management.

В следующей таблице указано как добавить поддержку для этой привязки в каждой среде разработки.The following table tells how to add support for this binding in each development environment.

Среда разработкиDevelopment environment Добавление поддержкиTo add support
Локальная разработка – библиотека классов C#Local development - C# class library Установка пакетаInstall the package
Локальная разработка — скрипт C#, JavaScript, F#, Java и PythonLocal development - C# script, JavaScript, F#, Java and Python Регистрация расширенияRegister the extension
Разработка на порталеPortal development Установка при добавлении выходной привязкиInstall when adding output binding

Дополнительные сведения об обновлении существующих расширений привязки на портале, не переиздавая проект приложения-функции, см. раздел Обновление расширений.To learn how to update existing binding extensions in the portal without having to republish your function app project, see Update your extensions.

ТриггерTrigger

Используйте триггер служебной шины для ответа на сообщения из очереди или раздела служебной шины.Use the Service Bus trigger to respond to messages from a Service Bus queue or topic.

Пример триггераTrigger - example

Языковой пример см. в разделах:See the language-specific example:

Пример C# в триггереTrigger - C# example

В следующем примере показана функция C#, которая считывает метаданные сообщения и заносит в журнал сообщение из очереди службы "Служебная шина".The following example shows a C# function that reads message metadata and logs a Service Bus queue message:

[FunctionName("ServiceBusQueueTriggerCSharp")]                    
public static void Run(
    [ServiceBusTrigger("myqueue", Connection = "ServiceBusConnection")] 
    string myQueueItem,
    Int32 deliveryCount,
    DateTime enqueuedTimeUtc,
    string messageId,
    ILogger log)
{
    log.LogInformation($"C# ServiceBus queue trigger function processed message: {myQueueItem}");
    log.LogInformation($"EnqueuedTimeUtc={enqueuedTimeUtc}");
    log.LogInformation($"DeliveryCount={deliveryCount}");
    log.LogInformation($"MessageId={messageId}");
}

Пример скрипта C# в триггереTrigger - C# script example

В следующем примере показаны привязка триггера служебной шины в файле function.json и функция сценария C#, которая использует эту привязку.The following example shows a Service Bus trigger binding in a function.json file and a C# script function that uses the binding. Функция считывает метаданные сообщения и заносит в журнал сообщение из очереди службы "Служебная шина".The function reads message metadata and logs a Service Bus queue message.

Данные привязки в файле function.json:Here's the binding data in the function.json file:

{
"bindings": [
    {
    "queueName": "testqueue",
    "connection": "MyServiceBusConnection",
    "name": "myQueueItem",
    "type": "serviceBusTrigger",
    "direction": "in"
    }
],
"disabled": false
}

Ниже приведен код скрипта C#.Here's the C# script code:

using System;

public static void Run(string myQueueItem,
    Int32 deliveryCount,
    DateTime enqueuedTimeUtc,
    string messageId,
    TraceWriter log)
{
    log.Info($"C# ServiceBus queue trigger function processed message: {myQueueItem}");

    log.Info($"EnqueuedTimeUtc={enqueuedTimeUtc}");
    log.Info($"DeliveryCount={deliveryCount}");
    log.Info($"MessageId={messageId}");
}

Пример F# в триггереTrigger - F# example

В следующем примере показаны привязка триггера служебной шины в файле function.json и функция F#, которая использует эту привязку.The following example shows a Service Bus trigger binding in a function.json file and an F# function that uses the binding. Эта функция заносит в журнал сообщение очереди служебной шины.The function logs a Service Bus queue message.

Данные привязки в файле function.json:Here's the binding data in the function.json file:

{
"bindings": [
    {
    "queueName": "testqueue",
    "connection": "MyServiceBusConnection",
    "name": "myQueueItem",
    "type": "serviceBusTrigger",
    "direction": "in"
    }
],
"disabled": false
}

Ниже приведен код сценария F#.Here's the F# script code:

let Run(myQueueItem: string, log: ILogger) =
    log.LogInformation(sprintf "F# ServiceBus queue trigger function processed message: %s" myQueueItem)

Пример Java в триггереTrigger - Java example

Следующая функция Java использует заметку @ServiceBusQueueTrigger из библиотеки среды выполнения функций Java для описания конфигурации триггера очереди служебной шины.The following Java function uses the @ServiceBusQueueTrigger annotation from the Java functions runtime library to describe the configuration for a Service Bus queue trigger. Функция извлекает сообщение, помещенное в очередь, и добавляет его в журналы.The function grabs the message placed on the queue and adds it to the logs.

@FunctionName("sbprocessor")
 public void serviceBusProcess(
    @ServiceBusQueueTrigger(name = "msg",
                             queueName = "myqueuename",
                             connection = "myconnvarname") String message,
   final ExecutionContext context
 ) {
     context.getLogger().info(message);
 }

Функции Java также могут быть активированы при добавлении сообщения в раздел служебной шины.Java functions can also be triggered when a message is added to a Service Bus topic. В следующем примере используется заметка @ServiceBusTopicTrigger для описания конфигурации триггера.The following example uses the @ServiceBusTopicTrigger annotation to describe the trigger configuration.

@FunctionName("sbtopicprocessor")
    public void run(
        @ServiceBusTopicTrigger(
            name = "message",
            topicName = "mytopicname",
            subscriptionName = "mysubscription",
            connection = "ServiceBusConnection"
        ) String message,
        final ExecutionContext context
    ) {
        context.getLogger().info(message);
    }

Пример JavaScript в триггереTrigger - JavaScript example

В следующем примере показаны привязка триггера служебной шины в файле function.json и функция JavaScript, которая использует эту привязку.The following example shows a Service Bus trigger binding in a function.json file and a JavaScript function that uses the binding. Функция считывает метаданные сообщения и заносит в журнал сообщение из очереди службы "Служебная шина".The function reads message metadata and logs a Service Bus queue message.

Данные привязки в файле function.json:Here's the binding data in the function.json file:

{
"bindings": [
    {
    "queueName": "testqueue",
    "connection": "MyServiceBusConnection",
    "name": "myQueueItem",
    "type": "serviceBusTrigger",
    "direction": "in"
    }
],
"disabled": false
}

Ниже показан код сценария JavaScript.Here's the JavaScript script code:

module.exports = function(context, myQueueItem) {
    context.log('Node.js ServiceBus queue trigger function processed message', myQueueItem);
    context.log('EnqueuedTimeUtc =', context.bindingData.enqueuedTimeUtc);
    context.log('DeliveryCount =', context.bindingData.deliveryCount);
    context.log('MessageId =', context.bindingData.messageId);
    context.done();
};

Пример Python: триггерTrigger - Python example

В следующем примере показано, как прочитать сообщение очереди ServiceBus с помощью триггера.The following example demonstrates how to read a ServiceBus queue message via a trigger.

В Function. JSON определена привязка servicebus, где type имеет значение serviceBusTrigger.A ServiceBus binding is defined in function.json where type is set to serviceBusTrigger.

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "name": "msg",
      "type": "serviceBusTrigger",
      "direction": "in",
      "queueName": "inputqueue",
      "connection": "AzureServiceBusConnectionString"
    }
  ]
}

Код в _init_. копировать объявляет параметр как func.ServiceBusMessage который позволяет читать сообщение очереди в функции.The code in _init_.py declares a parameter as func.ServiceBusMessage which allows you to read the queue message in your function.

import azure.functions as func

import logging
import json

def main(msg: func.ServiceBusMessage):
    logging.info('Python ServiceBus queue trigger processed message.')

    result = json.dumps({
        'message_id': msg.message_id,
        'body': msg.get_body().decode('utf-8'),
        'content_type': msg.content_type,
        'expiration_time': msg.expiration_time,
        'label': msg.label,
        'partition_key': msg.partition_key,
        'reply_to': msg.reply_to,
        'reply_to_session_id': msg.reply_to_session_id,
        'scheduled_enqueue_time': msg.scheduled_enqueue_time,
        'session_id': msg.session_id,
        'time_to_live': msg.time_to_live,
        'to': msg.to,
        'user_properties': msg.user_properties,
    })

    logging.info(result)

Атрибуты триггераTrigger - attributes

В библиотеках классов C# используйте следующие атрибуты для настройки триггера службы "Служебная шина":In C# class libraries, use the following attributes to configure a Service Bus trigger:

  • ServiceBusTriggerAttributeServiceBusTriggerAttribute

    Конструктор этого атрибута принимает имя очереди или раздела и подписки.The attribute's constructor takes the name of the queue or the topic and subscription. В Функциях Azure версии 1.х можно также указать права доступа для подключения.In Azure Functions version 1.x, you can also specify the connection's access rights. Если права доступа не указаны, то используется значение по умолчанию, Manage.If you don't specify access rights, the default is Manage. Дополнительные сведения см. в разделе Конфигурация триггера.For more information, see the Trigger - configuration section.

    Ниже приведен пример, в котором показано, как атрибут используется со строковым параметром.Here's an example that shows the attribute used with a string parameter:

    [FunctionName("ServiceBusQueueTriggerCSharp")]                    
    public static void Run(
        [ServiceBusTrigger("myqueue")] string myQueueItem, ILogger log)
    {
        ...
    }
    

    Чтобы указать учетную запись служебной шины, которую нужно использовать, можно задать свойство Connection, как показано в следующем примере.You can set the Connection property to specify the Service Bus account to use, as shown in the following example:

    [FunctionName("ServiceBusQueueTriggerCSharp")]                    
    public static void Run(
        [ServiceBusTrigger("myqueue", Connection = "ServiceBusConnection")] 
        string myQueueItem, ILogger log)
    {
        ...
    }
    

    Полный пример см. в разделе Пример C# в триггере.For a complete example, see Trigger - C# example.

  • ServiceBusAccountAttributeServiceBusAccountAttribute

    Предоставляет еще один способ указать используемую учетную запись служебной шины.Provides another way to specify the Service Bus account to use. Конструктор принимает имя параметра приложения, содержащего строку подключения к служебной шине.The constructor takes the name of an app setting that contains a Service Bus connection string. Атрибут может применяться на уровне класса, метода или параметра.The attribute can be applied at the parameter, method, or class level. Ниже показан пример уровня класса и метода.The following example shows class level and method level:

    [ServiceBusAccount("ClassLevelServiceBusAppSetting")]
    public static class AzureFunctions
    {
        [ServiceBusAccount("MethodLevelServiceBusAppSetting")]
        [FunctionName("ServiceBusQueueTriggerCSharp")]
        public static void Run(
            [ServiceBusTrigger("myqueue", AccessRights.Manage)] 
            string myQueueItem, ILogger log)
    {
        ...
    }
    

Используемая учетная запись служебной шины определяется в следующем порядке:The Service Bus account to use is determined in the following order:

  • Свойство ServiceBusTrigger атрибута Connection.The ServiceBusTrigger attribute's Connection property.
  • Атрибут ServiceBusAccount, примененный к тому же параметру, что и ServiceBusTrigger.The ServiceBusAccount attribute applied to the same parameter as the ServiceBusTrigger attribute.
  • Атрибут ServiceBusAccount, примененный к функции.The ServiceBusAccount attribute applied to the function.
  • Атрибут ServiceBusAccount, примененный к классу.The ServiceBusAccount attribute applied to the class.
  • Параметр приложения AzureWebJobsServiceBus.The "AzureWebJobsServiceBus" app setting.

Конфигурация триггераTrigger - configuration

В следующей таблице описываются свойства конфигурации привязки, которые задаются в файле function.json и атрибуте ServiceBusTrigger.The following table explains the binding configuration properties that you set in the function.json file and the ServiceBusTrigger attribute.

свойство function.jsonfunction.json property Свойство атрибутаAttribute property ОписаниеDescription
typetype Н/Дn/a Для этого свойства нужно задать значение "serviceBusTrigger".Must be set to "serviceBusTrigger". Это свойство задается автоматически при создании триггера на портале Azure.This property is set automatically when you create the trigger in the Azure portal.
directiondirection Н/Дn/a Для этого свойства необходимо задать значение "in".Must be set to "in". Это свойство задается автоматически при создании триггера на портале Azure.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 to monitor. Задается только в том случае, если отслеживается очередь, но не раздел.Set only if monitoring a queue, not for a topic.
topicNametopicName TopicNameTopicName Имя отслеживаемого раздела.Name of the topic to monitor. Задается только в том случае, если отслеживается раздел, но не очередь.Set only if monitoring a topic, not for a queue.
subscriptionNamesubscriptionName Параметр SubscriptionNameSubscriptionName Имя отслеживаемой подписки.Name of the subscription to monitor. Задается только в том случае, если отслеживается раздел, но не очередь.Set only if monitoring a topic, not for a queue.
подключениеconnection ConnectionConnection Имя параметра приложения, содержащего строку подключения к служебной шине, используемую для этой привязки.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.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. Строка подключения указывается для пространства имен служебной шины, и она не должна ограничиваться определенной очередью или разделом.The connection string must be for a Service Bus namespace, not limited to a specific queue or topic.
accessRightsaccessRights ДоступAccess Права доступа для строки подключения.Access rights for the connection string. Доступные значения: manage и listen.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". В противном случае выполнение операций, для которых требуются права на управление, в среде выполнения Функций Azure может завершиться ошибкой.Otherwise, the Functions runtime might fail trying to do operations that require manage rights. В функциях Azure версии 2. x и более поздних это свойство недоступно, поскольку последняя версия пакета SDK для хранилища не поддерживает управление операциями.In Azure Functions version 2.x and higher, this property is not available because the latest version of the Storage SDK doesn't support manage operations.

При локальной разработке параметры приложения перейдут в файл local.settings.json.When you're developing locally, app settings go into the local.settings.json file.

Использование триггераTrigger - usage

В C# и сценарии C# для сообщения очереди или раздела можно использовать параметры следующих типов:In C# and C# script, you can use the following parameter types for the queue or topic message:

  • string. Если сообщение является текстом.string - If the message is text.
  • byte[]. Используется для двоичных данных.byte[] - Useful for binary data.
  • Пользовательский тип. Если сообщение содержит JSON, то служба "Функции Azure" пытается выполнить десериализацию данных JSON.A custom type - If the message contains JSON, Azure Functions tries to deserialize the JSON data.
  • BrokeredMessage — выдается десериализованное сообщение с помощью метода BrokeredMessage. @ body<t > () .BrokeredMessage - Gives you the deserialized message with the BrokeredMessage.GetBody<T>() method.

Эти параметры предназначены для функций Azure версии 1. x; для 2. x и более поздних версий используйте Message вместо BrokeredMessage.These parameters are for Azure Functions version 1.x; for 2.x and higher, use Message instead of BrokeredMessage.

В JavaScript доступ к сообщению очереди или раздела осуществляется с помощью context.bindings.<name from function.json>.In JavaScript, access the queue or topic message by using context.bindings.<name from function.json>. Сообщение служебной шины передается в функцию в качестве строки или объекта JSON.The Service Bus message is passed into the function as either a string or JSON object.

Триггеры сообщений о сбоеTrigger - poison messages

В службе "Функции Azure" невозможно управление обработкой сообщений о сбое или настройка этой обработки.Poison message handling can't be controlled or configured in Azure Functions. Служебная шина сама обрабатывает сообщения о сбое.Service Bus handles poison messages itself.

Поведение PeekLock в триггереTrigger - PeekLock behavior

Среда выполнения службы "Функции" получает сообщение в режиме PeekLock.The Functions runtime receives a message in PeekLock mode. Она вызывает Complete для сообщения, если функция выполнена успешно, или Abandon в случае сбоя.It calls Complete on the message if the function finishes successfully, or calls Abandon if the function fails. Если функция выполняется дольше времени ожидания PeekLock, блокировка возобновляется автоматически до тех пор, пока выполняется функция.If the function runs longer than the PeekLock timeout, the lock is automatically renewed as long as the function is running.

Параметр maxAutoRenewDuration можно задать в файле host.json. Этот параметр сопоставляется с параметром OnMessageOptions.MaxAutoRenewDuration.The maxAutoRenewDuration is configurable in host.json, which maps to OnMessageOptions.MaxAutoRenewDuration. В соответствии с документацией по служебной шине максимально допустимое значение для этого параметра равно 5 минутам, тогда как ограничение времени выполнения функций можно увеличить с 5 минут по умолчанию до 10 минут.The maximum allowed for this setting is 5 minutes according to the Service Bus documentation, whereas you can increase the Functions time limit from the default of 5 minutes to 10 minutes. Этого не стоит делать для функций служебной шины, потому что лимит продления служебной шины будет превышен.For Service Bus functions you wouldn’t want to do that then, because you’d exceed the Service Bus renewal limit.

Метаданные сообщения триггераTrigger - message metadata

Триггер служебной шины предоставляет несколько свойств метаданных.The Service Bus trigger provides several metadata properties. Эти свойства можно использовать как часть выражений привязки в других привязках или как параметры в коде.These properties can be used as part of binding expressions in other bindings or as parameters in your code. Эти свойства относятся к классу BrokeredMessage.These are properties of the BrokeredMessage class.

СвойствоProperty ТипType ОписаниеDescription
DeliveryCount Int32 Число доставок.The number of deliveries.
DeadLetterSource string Источник недоставленных сообщений.The dead letter source.
ExpiresAtUtc DateTime Время окончания срока действия в формате UTC.The expiration time in UTC.
EnqueuedTimeUtc DateTime Время попадания в очередь в формате UTC.The enqueued time in UTC.
MessageId string Определяемое пользователем значение, используемое служебной шиной для выявления повторяющихся сообщений.A user-defined value that Service Bus can use to identify duplicate messages, if enabled.
ContentType string Идентификатор типа содержимого, используемый отправителем и получателем для логики конкретного приложения.A content type identifier utilized by the sender and receiver for application specific logic.
ReplyTo string Адрес очереди для ответа.The reply to queue address.
SequenceNumber Int64 Уникальный номер, назначенный сообщению службой "Служебная шина".The unique number assigned to a message by the Service Bus.
To string Адрес для отправки.The send to address.
Label string Метка конкретного приложения.The application specific label.
CorrelationId string Идентификатор корреляции.The correlation ID.

Примечание

В настоящее время триггер служебной шины, работающий с очередями с поддержкой сеансов и подписками, находится на этапе предварительной версии.Currently, Service bus trigger that works with session enabled queues and subscriptions is in preview. Отследите за этим элементом о дальнейших обновлениях.Please track this item for any further updates regarding this.

См. примеры кода, в которых используются эти свойства, в предыдущих разделах этой статьи.See code examples that use these properties earlier in this article.

Выходные данныеOutput

Используйте выходную привязку служебной шины Azure для отправки сообщений очереди или раздела.Use Azure Service Bus output binding to send queue or topic messages.

Пример выходных данныхOutput - example

Языковой пример см. в разделах:See the language-specific example:

Пример выходных данных C#Output - C# example

В следующем примере показана функция 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;
}

Пример выходных данных скрипта C#Output - C# script example

В следующем примере показаны выходная привязка служебной шины в файле function.json и функция сценария C#, которая использует эту привязку.The following example shows a Service Bus output binding in a function.json file and a C# script function that uses the binding. Функция использует триггер таймера для отправки сообщения очереди каждые 15 секунд.The function uses a timer trigger to send a queue message every 15 seconds.

Данные привязки в файле function.json:Here's the binding data in the function.json file:

{
    "bindings": [
        {
            "schedule": "0/15 * * * * *",
            "name": "myTimer",
            "runsOnStartup": true,
            "type": "timerTrigger",
            "direction": "in"
        },
        {
            "name": "outputSbQueue",
            "type": "serviceBus",
            "queueName": "testqueue",
            "connection": "MyServiceBusConnection",
            "direction": "out"
        }
    ],
    "disabled": false
}

Ниже приведен код сценария C#, который создает одно сообщение.Here's C# script code that creates a single message:

public static void Run(TimerInfo myTimer, ILogger log, out string outputSbQueue)
{
    string message = $"Service Bus queue message created at: {DateTime.Now}";
    log.LogInformation(message); 
    outputSbQueue = message;
}

Ниже приведен код сценария C#, который создает несколько сообщений.Here's C# script code that creates multiple messages:

public static async Task Run(TimerInfo myTimer, ILogger log, IAsyncCollector<string> outputSbQueue)
{
    string message = $"Service Bus queue messages created at: {DateTime.Now}";
    log.LogInformation(message); 
    await outputSbQueue.AddAsync("1 " + message);
    await outputSbQueue.AddAsync("2 " + message);
}

Пример выходных данных F#Output - F# example

В следующем примере показаны выходная привязка служебной шины в файле function.json и функция сценария F#, которая использует эту привязку.The following example shows a Service Bus output binding in a function.json file and an F# script function that uses the binding. Функция использует триггер таймера для отправки сообщения очереди каждые 15 секунд.The function uses a timer trigger to send a queue message every 15 seconds.

Данные привязки в файле function.json:Here's the binding data in the function.json file:

{
    "bindings": [
        {
            "schedule": "0/15 * * * * *",
            "name": "myTimer",
            "runsOnStartup": true,
            "type": "timerTrigger",
            "direction": "in"
        },
        {
            "name": "outputSbQueue",
            "type": "serviceBus",
            "queueName": "testqueue",
            "connection": "MyServiceBusConnection",
            "direction": "out"
        }
    ],
    "disabled": false
}

Ниже приведен код сценария F#, который создает одно сообщение.Here's F# script code that creates a single message:

let Run(myTimer: TimerInfo, log: ILogger, outputSbQueue: byref<string>) =
    let message = sprintf "Service Bus queue message created at: %s" (DateTime.Now.ToString())
    log.LogInformation(message)
    outputSbQueue = message

Пример выходных данных JavaOutput - Java example

В следующем примере показана функция Java, которая активируется HTTP-запросом и отправляет сообщение в очередь служебной шины myqueue.The following example shows a Java function that sends a message to a Service Bus queue myqueue when triggered by a HTTP request.

@FunctionName("httpToServiceBusQueue")
@ServiceBusQueueOutput(name = "message", queueName = "myqueue", connection = "AzureServiceBusConnection")
public String pushToQueue(
  @HttpTrigger(name = "request", methods = {HttpMethod.POST}, authLevel = AuthorizationLevel.ANONYMOUS)
  final String message,
  @HttpOutput(name = "response") final OutputBinding<T> result ) {
      result.setValue(message + " has been sent.");
      return message;
 }

В библиотеке среды выполнения функций Java используйте заметку @QueueOutput для параметров функции, значение которых будут записываться в очередь Служебной шины Microsoft Azure.In the Java functions runtime library, use the @QueueOutput annotation on function parameters whose value would be written to a Service Bus queue. Параметр должен быть типа OutputBinding<T>, где T — любой собственный тип Java POJO.The parameter type should be OutputBinding<T>, where T is any native Java type of a POJO.

Функции Java также могут записывать в раздел служебной шины.Java functions can also write to a Service Bus topic. В следующем примере используется заметка @ServiceBusTopicOutput для описания конфигурации выходной привязки.The following example uses the @ServiceBusTopicOutput annotation to describe the configuration for the output binding.

@FunctionName("sbtopicsend")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req", methods = {HttpMethod.GET, HttpMethod.POST}, authLevel = AuthorizationLevel.ANONYMOUS) HttpRequestMessage<Optional<String>> request,
            @ServiceBusTopicOutput(name = "message", topicName = "mytopicname", subscriptionName = "mysubscription", connection = "ServiceBusConnection") OutputBinding<String> message,
            final ExecutionContext context) {
        
        String name = request.getBody().orElse("Azure Functions");

        message.setValue(name);
        return request.createResponseBuilder(HttpStatus.OK).body("Hello, " + name).build();
        
    }

Пример выходных данных JavaScriptOutput - JavaScript example

В следующем примере показаны выходная привязка служебной шины в файле function.json и функция JavaScript, которая использует эту привязку.The following example shows a Service Bus output binding in a function.json file and a JavaScript function that uses the binding. Функция использует триггер таймера для отправки сообщения очереди каждые 15 секунд.The function uses a timer trigger to send a queue message every 15 seconds.

Данные привязки в файле function.json:Here's the binding data in the function.json file:

{
    "bindings": [
        {
            "schedule": "0/15 * * * * *",
            "name": "myTimer",
            "runsOnStartup": true,
            "type": "timerTrigger",
            "direction": "in"
        },
        {
            "name": "outputSbQueue",
            "type": "serviceBus",
            "queueName": "testqueue",
            "connection": "MyServiceBusConnection",
            "direction": "out"
        }
    ],
    "disabled": false
}

Ниже приведен код сценария JavaScript, который создает одно сообщение.Here's JavaScript script code that creates a single message:

module.exports = function (context, myTimer) {
    var message = 'Service Bus queue message created at ' + timeStamp;
    context.log(message);   
    context.bindings.outputSbQueue = message;
    context.done();
};

Ниже приведен код сценария JavaScript, который создает несколько сообщений.Here's JavaScript script code that creates multiple messages:

module.exports = function (context, myTimer) {
    var message = 'Service Bus queue message created at ' + timeStamp;
    context.log(message);   
    context.bindings.outputSbQueue = [];
    context.bindings.outputSbQueue.push("1 " + message);
    context.bindings.outputSbQueue.push("2 " + message);
    context.done();
};

Пример Python: выходные данныеOutput - Python example

В следующем примере показано, как выполнить запись в очередь ServiceBus в Python.The following example demonstrates how to write out to a ServiceBus queue in Python.

Определение привязки Сервицебуе определено в Function. JSON , где type имеет значение serviceBus.A ServiceBue binding definition is defined in function.json where type is set to serviceBus.

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "authLevel": "function",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "$return"
    },
    {
      "type": "serviceBus",
      "direction": "out",
      "connection": "AzureServiceBusConnectionString",
      "name": "msg",
      "queueName": "outqueue"
    }
  ]
}

В _init_. Корректировкаможно записать сообщение в очередь, передав значение методу set.In _init_.py, you can write out a message to the queue by passing a value to the set method.

import azure.functions as func

def main(req: func.HttpRequest, msg: func.Out[str]) -> func.HttpResponse:

    input_msg = req.params.get('message')

    msg.set(input_msg)

    return 'OK'

Выходные атрибутыOutput - attributes

В библиотеках классов 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. Выбор параметра прав доступа описан в разделе Привязки служебной шины в Функциях Azure.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, как показано в следующем примере.You can set the Connection property to specify the Service Bus account to use, as shown in the following example:

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

Полный пример см. в разделе Пример выходных данных C#.For a complete example, see Output - C# example.

Чтобы указать учетную запись служебной шины для использования на уровне класса, метода или параметра, можно применить атрибут ServiceBusAccount.You can use the ServiceBusAccount attribute to specify the Service Bus account to use at class, method, or parameter level. Дополнительные сведения см. в разделе Атрибуты триггера для предкомпилированного кода C#.For more information, see Trigger - attributes.

Выходная конфигурацияOutput - 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.jsonfunction.json property Свойство атрибутаAttribute property ОписаниеDescription
typetype Н/Дn/a Для этого свойства нужно задать значение "serviceBus".Must be set to "serviceBus". Это свойство задается автоматически при создании триггера на портале Azure.This property is set automatically when you create the trigger in the Azure portal.
directiondirection Н/Дn/a Для этого свойства необходимо задать значение out.Must be set to "out". Это свойство задается автоматически при создании триггера на портале Azure.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 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 to monitor. Задается только в случае отправки сообщений раздела, а не очереди.Set only if sending topic messages, not for a queue.
подключениеconnection ConnectionConnection Имя параметра приложения, содержащего строку подключения к служебной шине, используемую для этой привязки.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.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. Строка подключения указывается для пространства имен служебной шины, и она не должна ограничиваться определенной очередью или разделом.The connection string must be for a Service Bus namespace, not limited to a specific queue or topic.
accessRightsaccessRights ДоступAccess Права доступа для строки подключения.Access rights for the connection string. Доступные значения: manage и listen.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". В противном случае выполнение операций, для которых требуются права на управление, в среде выполнения Функций Azure может завершиться ошибкой.Otherwise, the Functions runtime might fail trying to do operations that require manage rights. В функциях Azure версии 2. x и более поздних это свойство недоступно, поскольку последняя версия пакета SDK для хранилища не поддерживает управление операциями.In Azure Functions version 2.x and higher, this property is not available because the latest version of the Storage SDK doesn't support manage operations.

При локальной разработке параметры приложения перейдут в файл local.settings.json.When you're developing locally, app settings go into the local.settings.json file.

Использование выходной привязкиOutput - usage

В Функциях Azure версии 1.x среда выполнения создает очередь, если ее не существует, и для параметра accessRights необходимо установить значение manage.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.

В C# и сценарии C# для привязки к выходным данным можно использовать параметры следующих типов:In C# and C# script, you can 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, то служба "Функции" создает сообщение с пустым объектом.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 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.

  • Чтобы получить доступ к ИДЕНТИФИКАТОРу сеанса, выполните привязку к типу Message и используйте свойство sessionId.To access the session ID, bind to a Message type and use the sessionId property.

В JavaScript доступ к очереди или разделу осуществляется с помощью context.bindings.<name from function.json>.In JavaScript, access the queue or topic by using context.bindings.<name from function.json>. Для context.binding.<name>можно назначить строку, массив байтов или объект JavaScript (десериализовать в JSON).You can assign a string, a byte array, or a JavaScript object (deserialized into JSON) to context.binding.<name>.

Чтобы отправить сообщение в очередь с поддержкой сеансов наC# языках, отличных от языка, используйте пакет SDK служебной шины Azure , а не встроенную выходную привязку.To send a message to a session-enabled queue in non-C# languages, use the Azure Service Bus SDK rather than the built-in output binding.

Исключения и коды возвратаExceptions and return codes

ПривязкаBinding Справочные материалыReference
Служебная шина AzureService Bus Коды ошибок службы "Служебная шина"Service Bus Error Codes
Служебная шина AzureService Bus Ограничения службы "Служебная шина"Service Bus Limits

Параметры файла host.jsonhost.json settings

В этом разделе описаны глобальные параметры конфигурации, доступные для этой привязки в версиях 2. x и более поздних.This section describes the global configuration settings available for this binding in versions 2.x and higher. Пример файла host. JSON ниже содержит только параметры этой привязки.The example host.json file below contains only the settings for this binding. Дополнительные сведения о глобальных параметрах конфигурации см. в справочнике по Host. JSON для функций Azure версии.For more information about global configuration settings, see host.json reference for Azure Functions version.

Примечание

Сведения о файле host.json в Функциях Azure версии 1.x см. в этой статье.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": false,
                "maxConcurrentCalls": 32,
                "maxAutoRenewDuration": "00:55:00"
            }
        }
    }
}
СвойствоProperty значение по умолчаниюDefault ОписаниеDescription
maxAutoRenewDurationmaxAutoRenewDuration 00:05:0000:05:00 Максимальный период времени, в течение которого блокировка сообщения будет продлеваться автоматически.The maximum duration within which the message lock will be renewed automatically.
autoCompleteautoComplete truetrue Триггер следует отметить как выполненный (автозавершение) или дождаться обработки вызова завершения.Whether the trigger should immediately mark as complete (autocomplete) or wait for processing to call complete.
maxConcurrentCallsmaxConcurrentCalls 1616 Максимальное число параллельных вызовов к обратному вызову, которое должен инициировать процесс обработки сообщений.The maximum number of concurrent calls to the callback that the message pump should initiate. По умолчанию в среде выполнения службы "Функции" одновременно обрабатывается несколько сообщений очереди.By default, the Functions runtime processes multiple messages concurrently. Чтобы среда выполнения обрабатывала в любой момент времени только одно сообщение очереди или раздела, для свойства maxConcurrentCalls нужно задать значение 1.To direct the runtime to process only a single queue or topic message at a time, set maxConcurrentCalls to 1.
prefetchCountprefetchCount Н/Дn/a Значение PrefetchCount по умолчанию, которое будет использоваться базовым компонентом MessageReceiver.The default PrefetchCount that will be used by the underlying MessageReceiver.

Дальнейшие действияNext steps