通过

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

  • 项目

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

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

安装扩展

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

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

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

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

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

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

使用 .NET CLI：

dotnet add package Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues --version 5.0.0

注意

Blob 存储、队列存储和表存储现在使用单独的扩展，并单独引用。 例如，若要在 .NET 隔离进程应用中同时使用 Blob 存储和队列存储触发器与绑定，应将以下包添加到项目：

Azure Cosmos DB for Table 扩展当前不支持独立进程。 如果你的应用需要使用 Azure 表，则必须使用 Microsoft.Azure.Functions.Worker.Extensions.Storage（版本 4.x）。 此包还有一个 5.x 版本，该版本仅引用 Blob 存储和队列存储的包。 在引用这些较新的拆分包时，请确保不要同时引用旧版组合存储包，否则会导致相同绑定的两种定义之间发生冲突。

安装捆绑包

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) 类型。
QueueMessage (Preview1)
消息。
BinaryData (Preview1)
消息的字节数。

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

队列输出绑定

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

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

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

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

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

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。

后续步骤