Привязки выходных данных хранилища очередей Azure для Функций 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 г. Настоятельно рекомендуется перенести приложения в изолированную рабочую модель для полной поддержки.

[Function(nameof(QueueFunction))]
[QueueOutput("output-queue")]
public string[] Run([QueueTrigger("input-queue")] Album myQueueItem, FunctionContext context)
{
    // Use a string array to return more than one message.
    string[] messages = {
        $"Album name = {myQueueItem.Name}",
        $"Album songs = {myQueueItem.Songs.ToString()}"};

    _logger.LogInformation("{msg1},{msg2}", messages[0], messages[1]);

    // Queue Output messages
    return messages;
}

В следующем примере показана функция Java, которая создает сообщение очереди, если оно активировано HTTP-запросом.

@FunctionName("httpToQueue")
@QueueOutput(name = "item", queueName = "myqueue-items", connection = "MyStorageConnectionAppSetting")
 public String pushToQueue(
     @HttpTrigger(name = "request", methods = {HttpMethod.POST}, authLevel = AuthorizationLevel.ANONYMOUS)
     final String message,
     @HttpOutput(name = "response") final OutputBinding<String> result) {
       result.setValue(message + " has been added.");
       return message;
 }

В библиотеке среды выполнения функций Java используйте заметку @QueueOutput для параметров, значения которых будут записываться в хранилище очередей. Параметр должен иметь тип OutputBinding<T>, где T — любой собственный тип Java POJO.

В следующем примере показана функция TypeScript с триггером HTTP, которая создает элемент очереди для каждого полученного HTTP-запроса.

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

const queueOutput = output.storageQueue({
    queueName: 'outqueue',
    connection: 'MyStorageConnectionAppSetting',
});

export async function httpTrigger1(request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> {
    const body = await request.text();
    context.extraOutputs.set(queueOutput, body);
    return { body: 'Created queue item.' };
}

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    extraOutputs: [queueOutput],
    handler: httpTrigger1,
});

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

context.extraOutputs.set(queueOutput, ['message 1', 'message 2']);

В следующем примере показана функция JavaScript с триггером HTTP, которая создает элемент очереди для каждого полученного HTTP-запроса.

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

const queueOutput = output.storageQueue({
    queueName: 'outqueue',
    connection: 'MyStorageConnectionAppSetting',
});

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    extraOutputs: [queueOutput],
    handler: async (request, context) => {
        const body = await request.text();
        context.extraOutputs.set(queueOutput, body);
        return { body: 'Created queue item.' };
    },
});

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

context.extraOutputs.set(queueOutput, ['message 1', 'message 2']);

В следующих примерах кода показано, как вывести сообщение очереди из функции, активируемой HTTP. Раздел конфигурации с параметром type класса queue определяет привязку для вывода.

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "Request",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "Response"
    },
    {
      "type": "queue",
      "direction": "out",
      "name": "Msg",
      "queueName": "outqueue",
      "connection": "MyStorageConnectionAppSetting"
    }
  ]
}

С помощью этой конфигурации привязки функция PowerShell может создать сообщение очереди с помощью Push-OutputBinding. В этом примере сообщение создается на основе строки запроса или параметра Body.

using namespace System.Net

# Input bindings are passed in via param block.
param($Request, $TriggerMetadata)

# Write to the Azure Functions log stream.
Write-Host "PowerShell HTTP trigger function processed a request."

# Interact with query parameters or the body of the request.
$message = $Request.Query.Message
Push-OutputBinding -Name Msg -Value $message
Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
    StatusCode = 200
    Body = "OK"
})

Чтобы отправить несколько сообщений одновременно, определите массив сообщений и используйте Push-OutputBinding для отправки сообщений в привязку для вывода очереди.

using namespace System.Net

# Input bindings are passed in via param block.
param($Request, $TriggerMetadata)

# Write to the Azure Functions log stream.
Write-Host "PowerShell HTTP trigger function processed a request."

# Interact with query parameters or the body of the request.
$message = @("message1", "message2")
Push-OutputBinding -Name Msg -Value $message
Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
    StatusCode = 200
    Body = "OK"
})

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

import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="QueueOutput1")
@app.route(route="message")
@app.queue_output(arg_name="msg", 
                  queue_name="<QUEUE_NAME>", 
                  connection="<CONNECTION_SETTING>")
def main(req: func.HttpRequest, msg: func.Out[str]) -> func.HttpResponse:
    input_msg = req.params.get('name')
    logging.info(input_msg)

    msg.set(input_msg)

    logging.info(f'name: {name}')
    return 'OK'

Атрибуты

Атрибут, определяющий выходную привязку в библиотеках C#, зависит от режима, в котором выполняется библиотека классов C#.

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

[Function(nameof(QueueFunction))]
[QueueOutput("output-queue")]
public string[] Run([QueueTrigger("input-queue")] Album myQueueItem, FunctionContext context)

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

Декораторы

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

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

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

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

Заметки

Заметка QueueOutput позволяет написать сообщение как выходной параметр функции. В следующем примере показана функция, активируемая HTTP, которая создает сообщение очереди.

package com.function;
import java.util.*;
import com.microsoft.azure.functions.annotation.*;
import com.microsoft.azure.functions.*;

public class HttpTriggerQueueOutput {
    @FunctionName("HttpTriggerQueueOutput")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req", methods = {HttpMethod.GET, HttpMethod.POST}, authLevel = AuthorizationLevel.FUNCTION) HttpRequestMessage<Optional<String>> request,
            @QueueOutput(name = "message", queueName = "messages", connection = "MyStorageConnectionAppSetting") OutputBinding<String> message,
            final ExecutionContext context) {

        message.setValue(request.getQueryParameters().get("name"));
        return request.createResponseBuilder(HttpStatus.OK).body("Done").build();
    }
}
Свойство Description
name Объявляет имя параметра в сигнатуре функции. При активации функции значение этого параметра будет иметь содержимое сообщения очереди.
queueName Объявляет имя очереди в учетной записи хранения.
connection Задает строку подключения к учетной записи хранения.

Параметр, связанный с заметкой QueueOutput, типизирован как экземпляр OutputBinding<T>.

Настройка

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

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

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

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

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

Свойство в function.json Описание
type Должен иметь значениеqueue. Это свойство задается автоматически при создании триггера на портале Azure.
direction Должен иметь значениеout. Это свойство задается автоматически при создании триггера на портале Azure.
name Имя переменной, представляющей очередь в коде функции. Задайте значение $return, ссылающееся на возвращаемое значение функции.
queueName Имя очереди.
Подключение Имя параметра или коллекции параметров приложения, указывающих, как подключиться к очередям Azure. См. раздел Подключения.

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

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

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

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

Изолированная библиотека классов рабочих процессов, скомпилированная функция C# выполняется в процессе, изолированном от среды выполнения.

Выберите версию, чтобы просмотреть сведения об использовании для режима и версии.

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

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

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

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

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

Существует два варианта для записи в очередь из функции с помощью заметки QueueOutput.

  • Возвращаемое значение. В результате применения заметки к самой функции возвращаемое значение функции записывается в очередь.

  • Императив. Чтобы явно задать значение сообщения, примените заметку к конкретному параметру типа OutputBinding<T>, где T находится POJO или любой собственный тип Java. При такой конфигурации при передаче значения в методу setValue значение записывается в очередь.

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

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

Существует два варианта записи из функции в настроенную очередь:

  • Возвращаемое значение: задайте name для свойства в function.json значение $return. В этой конфигурации возвращаемое значение функции сохраняется как сообщение очереди.

  • Императив. Передайте значение в метод set параметра, объявленного как тип Out . Значение, передаваемое в set, сохраняется как сообщение хранилища очереди.

Связи

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

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

Connection string

Чтобы получить строку подключения, выполните действия, описанные в разделе Управление ключами доступа к учетной записи хранения.

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

Если имя параметра приложения начинается с AzureWebJobs, можно указать только остальную часть имени. Например, если для connection задано значение MyStorage, среда выполнения Функций ищет параметр приложения с именем AzureWebJobsMyStorage. Если оставить connection пустым, среда выполнения Функций использует строку подключения по умолчанию служба хранилища из параметр приложения AzureWebJobsStorage.

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

Если вы используете расширение версии 5.x или выше (пакет 3.x или более поздней для стеков языка non-.NET), а не используете строка подключения с секретом, приложение может использовать удостоверение Microsoft Entra. Чтобы использовать удостоверение, вы определяете параметры под общим префиксом, который сопоставляется со connection свойством в конфигурации триггера и привязки.

Если для параметра connection "AzureWebJobs служба хранилища" задано значение "AzureWebJobs служба хранилища", см. Подключение размещение хранилища с удостоверением. Для всех других подключений требуются следующие свойства в расширении:

Свойство Шаблон переменной среды Description Пример значения
Универсальный код ресурса (URI) службы очередей <CONNECTION_NAME_PREFIX>__queueServiceUri1 URI плоскости данных службы очередей, к которой вы подключаетесь, с помощью схемы HTTPS. https://<storage_account_name>.queue.core.windows.net

1<CONNECTION_NAME_PREFIX>__serviceUri можно использовать в качестве псевдонима. Если указаны обе формы, queueServiceUri используется форма. Форму serviceUri нельзя использовать, если общая конфигурация подключения должна использоваться для больших двоичных объектов, очередей и (или) таблиц.

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

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

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

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

Внимание

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

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

Тип привязки Примеры встроенных ролей
Триггер Читатель данных очереди хранилища, Обработчик сообщений данных в очереди хранилища
Выходные привязки Участник для данных очереди хранилища, Отправитель сообщений данных в очередь хранилища

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

Привязка Справочные материалы
Queue Коды ошибок очередей
Большой двоичный объект, таблица, очередь Коды ошибок хранилища
Большой двоичный объект, таблица, очередь Устранение неполадок

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