使用英语阅读

通过

适用于 Azure Functions 的 Azure 队列存储触发器和绑定概述

  • 项目

Azure Functions 可以在创建新的 Azure 队列存储消息时运行，并可在函数中写入队列消息。

操作 类型
在队列存储数据更改时运行函数 触发器
写入队列存储消息 输出绑定

安装扩展

你安装的扩展 NuGet 包取决于你在函数应用中使用的 C# 模式：

重要

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

函数在与函数主机相同的进程中执行。 若要了解详细信息，请参阅使用 Azure Functions 开发 C# 类库函数。

在此模型的变体中，可以使用 C# 脚本运行 Functions，该脚本主要用于 C# 门户编辑。 若要更新在门户中运行的 C# 脚本应用程序的现有绑定扩展，而无需重新发布函数应用，请参阅更新扩展。

扩展的功能因扩展版本而异：

本节介绍如何使用类库。 对于 C# 脚本，需要改为安装扩展捆绑包版本 4.x。

此版本引入了使用标识而不是机密进行连接的功能。 有关使用托管标识配置函数应用的教程，请参阅使用基于标识的连接创建函数应用教程。

此版本允许绑定到 Azure.Storage.Queues 中的类型。

可以通过安装 Microsoft.Azure.WebJobs.Extensions.Storage.Queues NuGet 包版本 5.x 获得此扩展。

使用 .NET CLI：

dotnet add package Microsoft.Azure.WebJobs.Extensions.Storage.Queues

备注

Azure Blob、Azure 队列和 Azure 表现在使用单独的扩展并单独进行引用。 例如，若要在 .NET 进程内应用中为所有三个服务使用触发器和绑定，应将以下包添加到项目：

以前，这些扩展作为 Microsoft.Azure.WebJobs.Extensions.Storage 版本 4.x 一同交付。 此包还有一个 5.x 版本，该版本仅引用 Blob 和队列的拆分包。 因此，在从旧版本升级包引用时，可能需要额外引用新的 Microsoft.Azure.WebJobs.Extensions.Tables NuGet 包。 此外，在引用这些较新的拆分包时，请确保不要引用旧版组合存储包，否则会导致相同绑定的两种定义发生冲突。

安装捆绑包

Blob 存储绑定是在 host.json 项目文件中指定的扩展捆绑包的一部分。 你可能需要修改此捆绑包以更改绑定的版本，或者如果尚未安装捆绑包。 若要了解详细信息，请参阅扩展捆绑包。

此版本引入了使用标识而不是机密进行连接的功能。 有关使用托管标识配置函数应用的教程，请参阅使用基于标识的连接创建函数应用教程。

可以通过在 host.json 文件中添加或替换以下代码，从预览版扩展捆绑包 v3 添加该扩展的这一版本：

{
    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[3.3.0, 4.0.0)"
    }
}

若要了解详细信息，请参阅更新扩展。

绑定类型

.NET 支持的绑定类型取决于扩展版本和 C# 执行模式，可以是以下类型之一：

进程内类库是编译的 C# 函数，该函数在与 Functions 运行时相同的进程中运行。

请选择一个版本来查看模式和版本的绑定类型详细信息。

Azure 队列扩展支持下表所示的参数类型。

绑定方案 参数类型
队列触发器 QueueMessage
JSON 可序列化类型1
string
byte[]
BinaryData
队列输出（单个消息） QueueMessage
JSON 可序列化类型1
string
byte[]
BinaryData
队列输出（多个消息） QueueClient
ICollector<T> 或 IAsyncCollector<T>，其中 T 是单消息类型之一

1 包含 JSON 数据的消息可以反序列化为已知的普通旧 CLR 对象 (POCO) 类型。

host.json 设置

本部分介绍版本 2.x 及更高版本中可用于此绑定的配置设置。 host.json 文件中的设置将应用于函数应用实例中的所有函数。 下面的示例 host.json 文件仅包含此绑定的 2.x 版及更高版本设置。 若要详细了解版本 2.x 及更高版本中的函数应用程序配置设置，请参阅 Azure Functions 的 host.json 参考。

备注

有关 Functions 1.x 中 host.json 的参考，请参阅 Azure Functions 1.x 的 host.json 参考。

{
    "version": "2.0",
    "extensions": {
        "queues": {
            "maxPollingInterval": "00:00:02",
            "visibilityTimeout" : "00:00:30",
            "batchSize": 16,
            "maxDequeueCount": 5,
            "newBatchThreshold": 8,
            "messageEncoding": "base64"
        }
    }
}
属性 默认 说明
maxPollingInterval 00:01:00 队列轮询的最大间隔时间。 最小间隔为 00:00:00.100（100 毫秒）。 间隔最多可递增到 maxPollingInterval。 maxPollingInterval 的默认值为 00:01:00（1 分钟）。 maxPollingInterval 不得小于 00:00:00.100（100 毫秒）。 在 Functions 2.x 及更高版本中，数据类型为 TimeSpan。 在 Functions 1.x 中，它以毫秒为单位。
visibilityTimeout 00:00:00 消息处理失败时的重试间隔时间。
batchSize 16 Functions 运行时同时检索并并行处理的队列消息数。 当处理的数量下降到 newBatchThreshold 时，运行时可获取另一个批，并开始处理这些消息。 因此，每个函数处理的最大并发消息数是 batchSize 加上 newBatchThreshold。 此限制分别应用于各个队列触发的函数。

如果要避免对队列上收到的消息并行执行，可以将 batchSize 设置为 1。 但是，只有在函数应用仅于单个虚拟机 (VM) 上运行时，此设置才可消除并发。 如果函数应用横向扩展到多个 VM，每个 VM 可运行每个队列触发的函数的一个实例。

batchSize 的最大值为 32。
maxDequeueCount 5 在将某个消息移到有害队列之前，尝试处理该消息的次数。
newBatchThreshold N*batchSize/2 只要同时处理的消息数下降到此数值，运行时即检索另一个批次。

N 表示在应用服务或高级版计划上运行时可用的 vCPU 数目。 对于消耗计划，其值为 1。
messageEncoding base64 此设置仅适用于扩展包版本 5.0.0 和更高版本。 它表示消息的编码格式。 有效值为 base64 和 none。

后续步骤