通过

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

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

  • 项目

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

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

安装扩展

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

函数在独立的 C# 工作进程中执行。 若要了解详细信息，请参阅有关在独立工作进程中运行 C# Azure Functions 的指南。

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

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

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

此版本支持通过 .NET Aspire 集成配置触发器和绑定。

通过安装 NuGet 包版本 5.x 将该扩展添加到你的项目。

使用 .NET CLI：

dotnet add package Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues

注意

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

以前，这些扩展作为 Microsoft.Azure.Functions.Worker.Extensions.Storage 版本 4.x 一同交付。 此包还有一个 5.x 版本，该版本仅引用 Blob 和队列的拆分包。 因此，在从旧版本升级包引用时，可能需要额外引用新的 Microsoft.Azure.Functions.Worker.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# 函数在独立于运行时的进程中运行。

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

独立工作进程支持下表所示的参数类型。 对绑定到 Azure.Storage.Queues 中类型的支持目前处于预览阶段。

队列触发器

队列触发器可以绑定到以下类型：

类型 说明
string 消息内容即字符串。 当消息为简单文本时使用。
byte[] 消息的字节数。
JSON 可序列化类型 当队列消息包含 JSON 数据时，Functions 会尝试将 JSON 数据反序列化为普通的旧 CLR 对象 (POCO) 类型。
QueueMessage1 消息。
BinaryData1 消息的字节数。

1 若要使用这些类型，需要引用 Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues 5.2.0 或更高版本以及 SDK 类型绑定的常见依赖项。

队列输出绑定

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

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

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

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

对于其他输出方案，请直接从 Azure.Storage.Queues 创建并使用 QueueClient 和其他类型的队列。 有关使用依赖项注入从 Azure SDK 创建客户端类型的示例，请参阅 “注册 Azure 客户端 ”。

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。

后续步骤