Поделиться через

Выходная привязка Служебной шины Azure для службы "Функции Azure"

  • Статья

Используйте выходную привязку служебной шины Azure для отправки сообщений очереди или раздела.

Сведения об установке и настройке см. в обзорной статье.

Внимание

В этой статье используются вкладки для поддержки нескольких версий модели программирования Node.js. Модель версии 4 общедоступна и предназначена для более гибкого и интуитивно понятного интерфейса для разработчиков JavaScript и TypeScript. Дополнительные сведения о том, как работает модель версии 4, см. в руководстве разработчика по Функции Azure Node.js. Дополнительные сведения о различиях между версиями 3 и 4 см. в руководстве по миграции.

Функции Azure поддерживает две модели программирования для Python. Способ определения привязок зависит от выбранной модели программирования.

Модель программирования Python версии 2 позволяет определять привязки с помощью декораторов непосредственно в коде функции Python. Дополнительные сведения см. в руководстве разработчика Python.

Эта статья поддерживает обе модели программирования.

Пример

Функцию C# можно создать с помощью одного из следующих режимов C#:

  • Изолированная рабочая модель: скомпилированная функция C#, которая выполняется в рабочем процессе, изолированном от среды выполнения. Изолированный рабочий процесс необходим для поддержки функций C#, работающих в LTS и не LTS-версиях .NET и платформа .NET Framework. Расширения для изолированных рабочих процессов используют Microsoft.Azure.Functions.Worker.Extensions.* пространства имен.
  • Модель внутрипроцессного процесса: скомпилированная функция C#, которая выполняется в том же процессе, что и среда выполнения Функций. В варианте этой модели функции можно запускать с помощью скриптов C#, которая поддерживается главным образом для редактирования портала C#. Расширения для функций в процессе используют Microsoft.Azure.WebJobs.Extensions.* пространства имен.

Внимание

Поддержка будет завершена для модели в процессе 10 ноября 2026 г. Настоятельно рекомендуется перенести приложения в изолированную рабочую модель для полной поддержки.

Этот код определяет и инициализирует ILogger:

private readonly ILogger<ServiceBusReceivedMessageFunctions> _logger;

public ServiceBusReceivedMessageFunctions(ILogger<ServiceBusReceivedMessageFunctions> logger)
{
    _logger = logger;
}

В этом примере показана функция C#, которая получает сообщение и записывает его во вторую очередь:

[Function(nameof(ServiceBusReceivedMessageFunction))]
[ServiceBusOutput("outputQueue", Connection = "ServiceBusConnection")]
public string ServiceBusReceivedMessageFunction(
    [ServiceBusTrigger("queue", Connection = "ServiceBusConnection")] ServiceBusReceivedMessage message)
{
    _logger.LogInformation("Message ID: {id}", message.MessageId);
    _logger.LogInformation("Message Body: {body}", message.Body);
    _logger.LogInformation("Message Content-Type: {contentType}", message.ContentType);

    var outputMessage = $"Output message created at {DateTime.Now}";
    return outputMessage;
}

 

В этом примере используется триггер HTTP с объектом для OutputType отправки HTTP-ответа и записи выходного сообщения.

[Function("HttpSendMsg")]
public async Task<OutputType> Run([HttpTrigger(AuthorizationLevel.Function, "get", "post")] HttpRequestData req, FunctionContext context)
{
   _logger.LogInformation($"C# HTTP trigger function processed a request for {context.InvocationId}.");

   HttpResponseData response = req.CreateResponse(HttpStatusCode.OK);
   await response.WriteStringAsync("HTTP response: Message sent");

   return new OutputType()
   {
       OutputEvent = "MyMessage",
       HttpResponse = response
   };
}

Этот код определяет несколько типов OutputTypeвыходных данных, включая определение выходной привязки служебная шина дляOutputEvent:

 public class OutputType
{
   [ServiceBusOutput("TopicOrQueueName", Connection = "ServiceBusConnection")]
   public string OutputEvent { get; set; }

   public HttpResponseData HttpResponse { get; set; }
}

В примере ниже показана функция Java, которая активируется HTTP-запросом и отправляет сообщение в очередь Служебной шины myqueue.

@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. Параметр должен иметь тип OutputBinding<T>, где T — любой собственный тип Java POJO.

Функции Java также могут записывать данные в раздел Служебной шины. В примере ниже используется заметка @ServiceBusTopicOutput для описания конфигурации выходной привязки.

@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();

    }

В следующем примере показана функция TypeScript таймера, которая отправляет сообщение очереди каждые 5 минут.

import { app, InvocationContext, output, Timer } from '@azure/functions';

export async function timerTrigger1(myTimer: Timer, context: InvocationContext): Promise<string> {
    const timeStamp = new Date().toISOString();
    return `Message created at: ${timeStamp}`;
}

app.timer('timerTrigger1', {
    schedule: '0 */5 * * * *',
    return: output.serviceBusQueue({
        queueName: 'testqueue',
        connection: 'MyServiceBusConnection',
    }),
    handler: timerTrigger1,
});

Чтобы вывести несколько сообщений, верните массив вместо одного объекта. Например:

const timeStamp = new Date().toISOString();
const message = `Message created at: ${timeStamp}`;
return [`1: ${message}`, `2: ${message}`];

В следующем примере показана функция JavaScript, активировающая функцию JavaScript, которая отправляет сообщение очереди каждые 5 минут.

const { app, output } = require('@azure/functions');

const serviceBusOutput = output.serviceBusQueue({
    queueName: 'testqueue',
    connection: 'MyServiceBusConnection',
});

app.timer('timerTrigger1', {
    schedule: '0 */5 * * * *',
    return: serviceBusOutput,
    handler: (myTimer, context) => {
        const timeStamp = new Date().toISOString();
        return `Message created at: ${timeStamp}`;
    },
});

Чтобы вывести несколько сообщений, верните массив вместо одного объекта. Например:

const timeStamp = new Date().toISOString();
const message = `Message created at: ${timeStamp}`;
return [`1: ${message}`, `2: ${message}`];

В следующем примере показана выходная привязка Служебной шины в файле function.json и функция PowerShell, которая использует эту привязку.

Данные привязки в файле function.json:

{
  "bindings": [
    {
      "type": "serviceBus",
      "direction": "out",
      "connection": "AzureServiceBusConnectionString",
      "name": "outputSbMsg",
      "queueName": "outqueue",
      "topicName": "outtopic"
    }
  ]
}

Ниже приведена команда PowerShell, которая создает сообщение в качестве выходных данных функции.

param($QueueItem, $TriggerMetadata) 

Push-OutputBinding -Name outputSbMsg -Value @{ 
    name = $QueueItem.name 
    employeeId = $QueueItem.employeeId 
    address = $QueueItem.address 
}

В следующем примере показано, как выполнить запись в очередь Служебной шины в Python. Пример зависит от того, используется ли модель программирования Python версии 1 или версии 2.

import logging
import azure.functions as func

app = func.FunctionApp()

@app.route(route="put_message")
@app.service_bus_topic_output(arg_name="message",
                              connection="<CONNECTION_SETTING>",
                              topic_name="<TOPIC_NAME>")
def main(req: func.HttpRequest, message: func.Out[str]) -> func.HttpResponse:
    input_msg = req.params.get('message')
    message.set(input_msg)
    return 'OK'

Атрибуты

Библиотеки C# в процессе и изолированном рабочем процессе используют атрибуты для определения выходной привязки. Вместо этого скрипт C# использует файл конфигурации function.json, как описано в руководстве по скриптам C#.

В библиотеках классов C# для определения очереди или раздела, записанного в выходные данные, используйте атрибут ServiceBusOutputAttribute.

В следующей таблице описаны свойства, которые можно задать с помощью атрибута:

Свойство Description
EntityType Задает тип сущности: либо Queue для отправки сообщений в очередь, либо Topic при отправке сообщений в раздел.
QueueOrTopicName Имя раздела или очереди, в которую отправляются сообщения. Используйте EntityType для задания типа назначения.
Соединение Имя параметра или коллекции параметров приложения, указывающих, как подключиться к служебной шине. См. раздел Подключения.

Декораторы

Применяется только к модели программирования Python версии 2.

Для функций Python версии 2, определенных с помощью декоратора, в следующих свойствах service_bus_topic_output:

Свойство Description
arg_name Имя переменной, представляющей сообщение очереди или раздела в коде функции.
queue_name Имя очереди. Задается только в случае отправки сообщений очереди, а не раздела.
topic_name Имя раздела. Задается только в случае отправки сообщений раздела, а не очереди.
connection Имя параметра или коллекции параметров приложения, указывающих, как подключиться к служебной шине. См. раздел Подключения.

Сведения о функциях Python, определенных с помощью function.json, см. в разделе "Конфигурация ".

Заметки

Заметки ServiceBusQueueOutput и ServiceBusTopicOutput доступны для записи сообщения в качестве выходных данных функции. Параметр, снабженный этими заметками, должен быть объявлен как OutputBinding<T>, где T — тип, соответствующий типу сообщения.

Если разработка ведется на локальном компьютере, добавьте параметры приложения в файл local.settings.json в коллекции Values.

Настройка

Применяется только к модели программирования Python версии 1.

В следующей таблице описываются свойства, которые можно задать для options объекта, переданного методу output.serviceBusQueue() .

Свойство Description
queueName Имя очереди.
Подключение Имя параметра или коллекции параметров приложения, указывающих, как подключиться к служебной шине. См. раздел Подключения.

В следующей таблице описываются свойства, которые можно задать для options объекта, переданного методу output.serviceBusTopic() .

Свойство Description
topicName Имя раздела.
Подключение Имя параметра или коллекции параметров приложения, указывающих, как подключиться к служебной шине. См. раздел Подключения.

Если разработка ведется на локальном компьютере, добавьте параметры приложения в файл local.settings.json в коллекции Values.

В следующей таблице описываются свойства конфигурации привязки, которые задаются в файле function.json и атрибуте ServiceBus.

Свойство в function.json Описание
type Для этого свойства нужно задать значение "serviceBus". Это свойство задается автоматически при создании триггера на портале Azure.
direction Для этого свойства необходимо задать значение out. Это свойство задается автоматически при создании триггера на портале Azure.
name Имя переменной, представляющей сообщение очереди или раздела в коде функции. Задайте значение "$return", ссылающееся на возвращаемое значение функции.
queueName Имя очереди. Задается только в случае отправки сообщений очереди, а не раздела.
topicName Имя раздела. Задается только в случае отправки сообщений раздела, а не очереди.
Подключение Имя параметра или коллекции параметров приложения, указывающих, как подключиться к служебной шине. См. раздел Подключения.
accessRights (только в версии 1) Права доступа для строки подключения. Доступные значения: manage и listen. Значение по умолчанию — manage. Это означает, что у свойства connection есть разрешение на управление. При использовании строки подключения без разрешения на управление задайте для свойства accessRights значение "listen". В противном случае выполнение операций, для которых требуются права на управление, в среде выполнения Функций Azure может завершиться ошибкой. В Функциях Azure версии 2.x и более поздних это свойство недоступно, так как последняя версия пакета SDK Служебной шины не поддерживает операции управления.

Если разработка ведется на локальном компьютере, добавьте параметры приложения в файл local.settings.json в коллекции Values.

Подробные примеры см. в разделе Примеры.

Использование

Следующие типы выходных параметров поддерживаются всеми модальностями C# и версиями расширений:

Тип Описание
System.String Используется для записи простого текстового сообщения. Если при выходе из функции параметр имеет значение NULL, то служба "Функции" не создает сообщение.
byte[] Используется для записи сообщений с двоичными данными. Если при выходе из функции параметр имеет значение NULL, то служба "Функции" не создает сообщение.
Объект Если сообщение содержит JSON, функции сериализуют объект в полезные данные сообщения JSON. Если при выходе из функции параметр имеет значение NULL, то служба "Функции" создает сообщение с пустым объектом.

Типы параметров, относящихся к обмену сообщениями, содержат дополнительные метаданные сообщения. Определенные типы, поддерживаемые выходной привязкой, зависят от версии среды выполнения Функций, версии пакета расширения и используемой модальности C#.

Если требуется, чтобы функция записывала одно сообщение, служебная шина выходная привязка может привязаться к следующим типам:

Тип Описание
string Сообщение в виде строки. Используется, когда сообщение является простым текстом.
byte[] Байт сообщения.
Сериализуемые в JSON типы Объект, представляющий сообщение. Функции пытаются сериализовать обычный тип объекта CLR (POCO) в данные JSON.

Если требуется, чтобы функция записывала несколько сообщений, служебная шина выходная привязка может привязаться к следующим типам:

Тип Описание
T[] где T является одним из типов одного сообщения Массив, содержащий несколько сообщений. Каждая запись представляет одно сообщение.

Для других сценариев вывода создайте и используйте ServiceBusClient с другими типами из Azure.Messaging.ServiceBus напрямую. Пример использования внедрения зависимостей для создания типа клиента из пакета SDK Azure см. в статье "Регистрация клиентов Azure".

В Функциях Azure версии 1.x среда выполнения создает очередь, если ее не существует, и для параметра accessRights необходимо установить значение manage. В Функции Azure версии 2.x и выше очередь или раздел уже должны существовать. Если указать очередь или раздел, который не существует, функция завершается ошибкой.

Используйте пакет SDK Служебной шины Azure, а не встроенную выходную привязку.

Доступ к выходному сообщению, возвращая значение напрямую или используя context.extraOutputs.set().

Вывод в Служебную шину доступен через командлет Push-OutputBinding, где вы передаете аргументы, соответствующие имени, заданному с помощью параметра привязки имени в файле function.json.

Используйте пакет SDK Служебной шины Azure, а не встроенную выходную привязку.

Полный пример см. в разделе Примеры.

Связи

Свойство connection является ссылкой на конфигурацию среды, которая указывает, как приложение должно подключаться к служебной шине. В данном свойстве может быть указано:

Если настроенное значение одновременно точно соответствует одному параметру и является префиксом для других параметров, то используется точное совпадение.

Connection string

Чтобы получить строку подключения, следуйте инструкциям, указанным в разделе Получение учетных данных управления. Строка подключения указывается для пространства имен служебной шины, и она не должна ограничиваться определенной очередью или разделом.

Эта строка подключения должна храниться в параметре приложения с именем, соответствующим значению, которое указано свойством connection конфигурации привязки.

Если имя параметра приложения начинается с AzureWebJobs, можно указать только остальную часть имени. Например, если задать для connection значение MyServiceBus, то среда выполнения Функций Azure будет искать параметр приложения AzureWebJobsMyServiceBus. Если оставить строку connection пустой, то среда выполнения службы "Функции" будет использовать строку подключения к служебной шине по умолчанию для параметра приложения AzureWebJobsServiceBus.

Подключения на основе удостоверений

Если вы используете расширение версии 5.x или выше, вместо использования строка подключения с секретом, вы можете использовать удостоверение Microsoft Entra. Для этого необходимо определить параметры под общим префиксом, который соответствует свойству connection в конфигурации триггера и привязки.

В этом режиме для расширения требуются следующие свойства:

Свойство Шаблон переменной среды Description Пример значения
Пространство полных имен <CONNECTION_NAME_PREFIX>__fullyQualifiedNamespace Полное пространство имен служебной шины. <пространство_имен_служебной шины>.servicebus.windows.net

Для настройки подключения можно задать дополнительные свойства. См. раздел Общие свойства подключений на основе удостоверений.

Примечание.

При использовании Конфигурации приложений Azure или Key Vault для предоставления параметров подключений Управляемого удостоверения имена параметров должны использовать допустимый разделитель ключей, например : или /, вместо __, чтобы обеспечить правильное разрешение имен.

Например, <CONNECTION_NAME_PREFIX>:fullyQualifiedNamespace.

При размещении в службе "Функции Azure" для подключений на основе удостоверений используется управляемое удостоверение. По умолчанию используется назначаемое системой удостоверение, однако вы можете указать назначаемое пользователем удостоверение с помощью свойств credential и clientID. Обратите внимание, что настройка назначаемого пользователем удостоверения с идентификатором ресурса не поддерживается. При выполнении в других контекстах, например при локальной разработке, вместо этого используется удостоверение разработчика, хотя это можно настроить. См. раздел Локальная разработка с использованием подключений на основе удостоверений.

Предоставление разрешения удостоверению

Любое используемое удостоверение должно иметь разрешения на выполнение предполагаемых действий. Для большинства служб Azure это означает, что необходимо назначить роль в Azure RBAC, используя встроенные или настраиваемые роли, которые предоставляют эти разрешения.

Внимание

Иногда целевая служба может предоставлять разрешения, которые не являются обязательными для всех контекстов. Там, где это возможно, придерживайтесь принципа минимальных привилегий, предоставляя удостоверению лишь самые необходимые привилегии. Например, если приложению требуется только возможность чтения из источника данных, используйте роль, которая имеет разрешение только на чтение. Было бы неуместным назначить роль, которая также разрешает запись в эту службу, так как это разрешение не требуется для операции чтения. Соответственно необходимо еще проверить, что область действия назначенной роли ограничена только теми ресурсами, которые необходимо прочитать.

Вам потребуется создать назначение ролей, которое предоставляет доступ к темам и очередям во время выполнения. Ролей управления, таких как Владелец, недостаточно. В следующей таблице показаны встроенные роли, которые рекомендуется использовать вместе с расширением служебной шины при обычной работе. Приложению могут потребоваться дополнительные разрешения в зависимости от написанного кода.

Тип привязки Примеры встроенных ролей
Триггер1 Получатель данных Служебной шины Azure, Владелец данных служебной шины Azure
Выходные привязки Отправитель данных Служебной шины Azure

1 Для активации из разделов служебной шины назначение роли должно иметь эффективную область действия, в которую входят ресурсы подписки служебной шины. Если включен только раздел, отобразится ошибка. Некоторые клиенты, такие как портал Azure, не предоставляют ресурс подписки служебной шины в качестве области назначения ролей. В таких случаях вместо этого можно использовать Azure CLI. Для получения дополнительных сведений см. раздел Встроенные роли Azure для служебной шины Azure.

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

Привязка Справочные материалы
Cлужебная шина Коды ошибок службы "Служебная шина"
Cлужебная шина Ограничения службы "Служебная шина"

Следующие шаги