适用于 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 毫秒)。 间隔最多可递增到 maxPollingIntervalmaxPollingInterval 的默认值为 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 和更高版本。 它表示消息的编码格式。 有效值为 base64none

后续步骤