你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

适用于 Azure Functions 的 Azure 队列存储输出绑定

项目
08/15/2024

Azure Functions 可以通过设置输出绑定来创建新的 Azure 队列存储消息。

有关设置和配置详细信息，请参阅概述。

重要

本文使用选项卡来支持多个版本的 Node.js 编程模型。 v4 模型已正式发布，旨在为 JavaScript 和 TypeScript 开发人员提供更为灵活和直观的体验。有关 v4 模型工作原理的更多详细信息，请参阅 Azure Functions Node.js 开发人员指南。要详细了解 v3 和 v4 之间的差异，请参阅迁移指南。

Azure Functions 支持两种 Python 编程模型。定义绑定的方式取决于选择的编程模型。

使用 Python v2 编程模型，可以直接在 Python 函数代码中使用修饰器定义绑定。有关详细信息，请参阅 Python 开发人员指南。

本文同时支持两个编程模型。

示例

可使用以下 C# 模式之一来创建 C# 函数：

独立辅助角色模型：编译的 C# 函数，该函数在独立于运行时的工作进程中运行。需要独立工作进程才能支持在 LTS 和非 LTS 版 .NET 和 .NET Framework 上运行的 C# 函数。独立工作进程函数的扩展使用 Microsoft.Azure.Functions.Worker.Extensions.* 命名空间。
进程内模型：编译的 C# 函数，该函数在与 Functions 运行时相同的进程中运行。在此模型的变体中，可以使用 C# 脚本运行 Functions，该脚本主要用于 C# 门户编辑。进程内函数的扩展使用 Microsoft.Azure.WebJobs.Extensions.* 命名空间。

重要

对进程内模型的支持将于 2026 年 11 月 10 日结束。为获得完全支持，强烈建议将应用迁移到独立工作模型。

独立工作模型
进程模型

[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;
}

以下示例演示针对收到的每个 HTTP 请求创建队列消息的C# 函数。

[StorageAccount("MyStorageConnectionAppSetting")]
public static class QueueFunctions
{
    [FunctionName("QueueOutput")]
    [return: Queue("myqueue-items")]
    public static string QueueOutput([HttpTrigger] dynamic input,  ILogger log)
    {
        log.LogInformation($"C# function processed: {input.Text}");
        return input.Text;
    }
}

有关如何配置到队列存储的输出绑定的端到端示例，请参阅以下文章之一：

以下示例显示了一个 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 是 POJO 的任何本机 Java 类型。

有关如何配置到队列存储的输出绑定的端到端示例，请参阅以下文章之一：

模型 v4
模型 v3

以下示例显示 HTTP 触发的 TypeScript 函数，该函数为收到的每个 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']);

模型 v4
模型 v3

以下示例显示 HTTP 触发的 JavaScript 函数，该函数为收到的每个 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']);

有关如何配置到队列存储的输出绑定的端到端示例，请参阅以下文章之一：

以下示例演示 function.json 文件中的一个 HTTP 触发器绑定以及使用该绑定的 JavaScript 函数。该函数针对收到的每个 HTTP 请求创建一个队列项。

function.json 文件如下所示：

{
  "bindings": [
    {
      "type": "httpTrigger",
      "direction": "in",
      "authLevel": "function",
      "name": "input"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "$return"
    },
    {
      "type": "queue",
      "direction": "out",
      "name": "myQueueItem",
      "queueName": "outqueue",
      "connection": "MyStorageConnectionAppSetting"
    }
  ]
}

配置部分解释了这些属性。

JavaScript 代码如下所示：

module.exports = async function (context, input) {
    context.bindings.myQueueItem = input.body;
};

可以通过定义 myQueueItem 输出绑定的消息数组，一次性发送多条消息。以下 JavaScript 代码针对收到的每个 HTTP 请求发送两条包含硬编码值的队列消息。

module.exports = async function(context) {
    context.bindings.myQueueItem = ["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 创建队列消息。在此示例中，将通过查询字符串或正文参数创建消息。

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 所需的配置都是相同的。该示例取决于是使用 v1 还是 v2 Python 编程模型。

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'

有关如何配置到队列存储的输出绑定的端到端示例，请参阅以下文章之一：

存储队列绑定在 function.json 中定义，其中 type 设置为 queue。

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

若要在队列中设置单个消息，请将单个值传递给 set 方法。

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'

若要在队列中创建多个消息，请将参数声明为适当的列表类型，并将值的数组（与列表类型匹配）传递给 set 方法。

import azure.functions as func
import typing

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

    msg.set(['one', 'two'])

    return 'OK'

特性

在 C# 库中定义输出绑定的特性取决于 C# 类库的运行模式。

独立工作模型
进程模型

在独立工作进程中运行时，请使用 QueueOutputAttribute，它采用队列的名称，如以下示例所示：

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

在独立工作进程中运行时，仅支持返回的变量。不能使用输出参数。

在 C# 类库中，使用 QueueAttribute。 C# 脚本改用 function.json 配置文件，如 C# 脚本指南中所述。

该特性将应用到 out 参数，或应用到函数的返回值。该特性的构造函数采用队列的名称，如以下示例中所示：

[FunctionName("QueueOutput")]
[return: Queue("myqueue-items")]
public static string Run([HttpTrigger] dynamic input,  ILogger log)
{
    ...
}

可以设置 Connection 属性来指定要使用的存储帐户，如以下示例中所示：

[FunctionName("QueueOutput")]
[return: Queue("myqueue-items", Connection = "StorageConnectionAppSetting")]
public static string Run([HttpTrigger] dynamic input,  ILogger log)
{
    ...
}

可以使用 StorageAccount 特性在类、方法或参数级别指定存储帐户。有关详细信息，请参阅“触发器 - 特性”。

修饰符

仅适用于 Python v2 编程模型。

对于使用修饰器定义的 Python v2 功能，支持 queue_output 上的以下属性：

properties	说明
`arg_name`	表示函数代码中的队列的变量的名称。
`queue_name`	队列的名称。
`connection`	指定如何连接到 Azure 队列的应用设置或设置集合的名称。请参阅连接。

对于使用 function.json 定义的 Python 函数，请参阅“配置”部分。

批注

使用 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();
    }
}

属性	说明
`name`	在函数签名中声明参数名称。触发函数时，此参数的值包含队列消息的内容。
`queueName`	在存储帐户中声明队列名称。
`connection`	指向存储帐户连接字符串。

与 QueueOutput 注释关联的参数类型化为 OutputBinding<T> 实例。

配置

仅适用于 Python v1 编程模型。

模型 v4
模型 v3

下表说明了可以在传递给 output.storageQueue() 方法的 options 对象上设置的属性。

properties	说明
queueName	队列的名称。
连接	指定如何连接到 Azure 队列的应用设置或设置集合的名称。请参阅连接。

下表解释了在 function.json 文件中设置的绑定配置属性。

属性	说明
type	必须设置为 `queue`。在 Azure 门户中创建触发器时，会自动设置此属性。
direction	必须设置为 `out`。在 Azure 门户中创建触发器时，会自动设置此属性。
name	表示函数代码中的队列的变量的名称。设置为 `$return` 可引用函数返回值。
queueName	队列的名称。
连接	指定如何连接到 Azure 队列的应用设置或设置集合的名称。请参阅连接。

在本地开发时，需要将应用程序设置添加到 Values 集合中的 local.settings.json 文件中。

下表解释了在 function.json 文件中设置的绑定配置属性。

“function.json”属性	说明
type	必须设置为 `queue`。在 Azure 门户中创建触发器时，会自动设置此属性。
direction	必须设置为 `out`。在 Azure 门户中创建触发器时，会自动设置此属性。
name	表示函数代码中的队列的变量的名称。设置为 `$return` 可引用函数返回值。
queueName	队列的名称。
连接	指定如何连接到 Azure 队列的应用设置或设置集合的名称。请参阅连接。

在本地开发时，请将应用程序设置添加到 Values 集合的 local.settings.json 文件。

有关完整示例，请参阅示例部分。

使用情况

队列输出绑定的用法取决于扩展包版本，以及函数应用中使用的 C# 形式，可以是以下形式之一：

独立工作模型
进程模型

独立工作进程类库的已编译 C# 函数在独立于运行时的进程中运行。

选择一个版本以查看模式和版本的使用情况详细信息。

使用 out T paramName 等方法参数写入一条队列消息。可以使用方法返回类型而不使用 out 参数，T 可为以下任何类型：

可序列化为 JSON 的对象
string
byte[]
QueueMessage

有关使用这些类型的示例，请参阅扩展的 GitHub 存储库。

可使用以下类型之一将多条消息写入队列：

ICollector<T> 或 IAsyncCollector<T>
QueueClient

有关使用 QueueMessage 和 QueueClient 的示例，请参阅扩展的 GitHub 存储库。

尽管该特性采用 Connection 属性，但你也可以使用 StorageAccountAttribute 来指定存储帐户连接。如果需要使用一个不同于库中的其他函数的存储帐户，可以执行此操作。构造函数采用包含存储连接字符串的应用设置的名称。可以在参数、方法或类级别应用该特性。以下示例演示类级别和方法级别：

[StorageAccount("ClassLevelStorageAppSetting")]
public static class AzureFunctions
{
    [FunctionName("StorageTrigger")]
    [StorageAccount("FunctionLevelStorageAppSetting")]
    public static void Run( //...
{
    ...
}

要使用的存储帐户按以下顺序确定：

触发器或绑定特性的 Connection 属性。
作为触发器或绑定特性应用到同一参数的 StorageAccount 特性。
应用到函数的 StorageAccount 特性。
应用到类的 StorageAccount 特性。
函数应用的默认存储帐户，在 AzureWebJobsStorage 应用程序设置中定义。

使用 out T paramName 等方法参数写入一条队列消息。可以使用方法返回类型而不使用 out 参数，T 可为以下任何类型：

可序列化为 JSON 的对象
string
byte[]
CloudQueueMessage

如果在尝试绑定到 CloudQueueMessage 时收到错误消息，请确保已引用正确的存储 SDK 版本。

可使用以下类型之一将多条消息写入队列：

ICollector<T> 或 IAsyncCollector<T>
CloudQueue

[StorageAccount("ClassLevelStorageAppSetting")]
public static class AzureFunctions
{
    [FunctionName("StorageTrigger")]
    [StorageAccount("FunctionLevelStorageAppSetting")]
    public static void Run( //...
{
    ...
}

要使用的存储帐户按以下顺序确定：

触发器或绑定特性的 Connection 属性。
作为触发器或绑定特性应用到同一参数的 StorageAccount 特性。
应用到函数的 StorageAccount 特性。
应用到类的 StorageAccount 特性。
函数应用的默认存储帐户，在 AzureWebJobsStorage 应用程序设置中定义。

如果希望函数写入单个消息，队列输出绑定可以绑定到以下类型：

类型	说明
`string`	消息内容即字符串。当消息为简单文本时使用。
`byte[]`	消息的字节数。
JSON 可序列化类型	表示 JSON 消息内容的对象。函数尝试将普通旧 CLR 对象 (POCO) 类型序列化为 JSON 数据。

如果希望函数写入多个消息，队列输出绑定可以绑定到以下类型：

类型	说明
`T[]`，其中 `T` 是单消息类型之一	包含多个消息的内容的数组。每个条目表示一个消息。

对于其他输出方案，请直接创建和使用 Azure.Storage.Queues 中的类型。

可使用两个选项通过 QueueOutput 注释将数据从函数写入队列：

返回值：通过将注释应用于函数本身，函数的返回值将写入到队列中。
命令性：若要显式设置消息值，请将注释应用于 OutputBinding<T> 类型的特定参数，其中 T 是 POJO 或任何本机 Java 类型。使用此配置时，将值传递给 setValue 方法就会将值写入队列。

模型 v4
模型 v3

通过直接返回值或使用 context.extraOutputs.set() 来访问输出队列项。可对队列项有效负载使用字符串或 JSON 可序列化对象。

通过 Push-OutputBinding 可以输出到队列消息，你在其中传递的参数与 function.json 文件中绑定的 name 参数指定的名称匹配。

可以通过两个选项将数据从函数写入到已配置的队列：

返回值：将 function.json 中的 name 属性设置为 $return。使用此配置时，函数的返回值将作为队列存储消息保留。
命令性：将值传递给声明为 Out 类型的参数的 set 方法。传递给 set 的值将作为队列存储消息保留。

连接

connection 属性是对环境配置的引用，它指定应用应如何连接到 Azure 队列。它可能指定：

包含连接字符串的应用程序设置的名称
多个应用程序设置的共享前缀的名称，共同定义基于标识的连接。

如果配置的值既是单个设置的完全匹配，也是其他设置的前缀匹配，则使用完全匹配。

连接字符串

若要获取连接字符串，请执行管理存储帐户访问密钥中显示的步骤。

此连接字符串应存储在应用程序设置中，其名称与绑定配置的 connection 属性指定的值匹配。

如果应用设置名称以“AzureWebJobs”开始，则只能在此处指定该名称的余下部分。例如，如果将 connection 设置为“MyStorage”，Functions 运行时将会查找名为“AzureWebJobsMyStorage”的应用设置。如果将 connection 留空，Functions 运行时将使用应用设置中名为 AzureWebJobsStorage 的默认存储连接字符串。

基于标识的连接

如果使用的是 5.x 或更高版本的扩展（non-.NET 语言堆栈捆绑 3.x 或更高版本），则可以让应用使用Microsoft Entra 标识，而不是将连接字符串与机密一起使用。要使用标识，需要定义公共前缀下的设置，该前缀映射到触发器和绑定配置中的 connection 属性。

如果将 connection 设置为“AzureWebJobsStorage”，请参阅使用标识连接到主机存储。对于所有其他连接，扩展需要以下属性：

属性	环境变量模板	说明	示例值
队列服务 URI	`<CONNECTION_NAME_PREFIX>__queueServiceUri`¹	要连接到的队列服务的数据平面 URI，使用 HTTPS 方案。	https://<storage_account_name>.queue.core.windows.net

¹ <CONNECTION_NAME_PREFIX>__serviceUri 可以用作别名。如果同时提供了两个窗体，则会使用 queueServiceUri 窗体。如果要跨 Blob、队列和/或表使用总体连接配置，则无法使用 serviceUri 窗体。

可以设置其他属性来自定义连接。请参阅基于标识的连接的通用属性。

在 Azure Functions 服务中托管时，基于标识的连接将使用托管标识。默认情况下使用系统分配的标识，但可以使用 credential 和 clientID 属性来指定用户分配的标识。请注意，不支持为用户分配的标识配置资源 ID。在其他上下文（如本地开发）中运行时，将改用开发人员标识，尽管可以进行自定义。请参阅使用基于标识的连接进行本地开发。

向标识授予权限

无论使用何种标识，都必须具有执行所需操作的权限。对于大多数 Azure 服务，这意味着你需要使用内置角色或者提供这些权限的自定义角色在 Azure RBAC 中分配角色。

重要

某些权限可能由并非所有上下文都需要的目标服务公开。尽可能遵循最低权限原则，仅授予标识所需的权限。例如，如果应用只需要从数据源进行读取即可，则使用仅具有读取权限的角色。分配一个也具有该服务写入权限的角色并不恰当，因为对于读取操作来说，写入是多余的权限。同样，你也希望确保角色分配的范围仅限于需要读取的资源。

你将需要创建一个角色分配，以便在运行时提供对队列的访问权限。所有者等管理角色还不够。下表显示了在正常操作中使用队列存储扩展时建议使用的内置角色。根据所编写的代码，应用程序可能需要具有其他权限。

绑定类型	内置角色示例
触发器	存储队列数据读取者、存储队列数据消息处理者
输出绑定	存储队列数据参与者、存储队列数据消息发送方

异常和返回代码

绑定	参考
队列	队列错误代码
Blob、表、队列	存储错误代码
Blob、表、队列	故障排除

后续步骤

在队列存储数据更改时运行函数（触发器）

通过

适用于 Azure Functions 的 Azure 队列存储输出绑定

示例

特性

修饰符

批注

配置

使用情况

连接

连接字符串

基于标识的连接

向标识授予权限

异常和返回代码

后续步骤

反馈

其他资源