Azure Functions 的 Azure 服务总线绑定

Azure Functions 通过触发器和绑定Azure 服务总线集成。 与服务总线集成后,你可以构建响应和发送队列或主题消息的函数。

操作 类型
创建服务总线队列或主题消息时运行函数 触发器
发送 Azure 服务总线消息 输出绑定

安装扩展

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

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

通过安装此 NuGet 包将该扩展添加到你的项目。

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

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

此版本允许绑定到 Azure.Messaging.ServiceBus 中的类型。

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

安装捆绑包

服务总线绑定是在 host.json 项目文件中指定的扩展捆绑包的一部分。 如果尚未安装捆绑包,你可能需要修改此捆绑包才能更改绑定的版本。 若要了解详细信息,请参阅扩展捆绑包

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

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

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

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

绑定类型

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

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

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

独立工作进程支持下表所示的参数类型。

服务总线触发器

如果希望函数处理单条消息,服务总线触发器可以绑定到以下类型:

类型 说明
string 字符串格式的消息。 当消息为简单文本时使用。
byte[] 消息的字节数。
JSON 可序列化类型 当事件包含 JSON 数据时,Functions 会尝试将 JSON 数据反序列化为普通的旧 CLR 对象 (POCO) 类型。
ServiceBusReceivedMessage (预览版1
消息对象。

如果希望函数处理一批消息,服务总线触发器可以绑定到以下类型:

类型 说明
T[],其中 T 是单消息类型之一 批处理中的事件数组。 每个条目表示一个事件。

独立进程模型尚不支持服务总线触发器的消息解决方案。

1 若要使用这些类型,需要引用 Microsoft.Azure.Functions.Worker.Extensions.ServiceBus 5.10.0-preview2 或更高版本以及 SDK 类型绑定的常见依赖项

服务总线输出绑定

如果希望函数写入单个消息,服务总线输出绑定可以绑定到以下类型:

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

如果希望函数写入多个消息,服务总线输出绑定可以绑定到以下类型:

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

对于其他输出方案,请直接创建和使用 Azure.Messaging.ServiceBus 中的类型。

host.json 设置

本部分介绍可用于此绑定的配置设置,具体取决于运行时和扩展版本。

{
    "version": "2.0",
    "extensions": {
        "serviceBus": {
            "clientRetryOptions":{
                "mode": "exponential",
                "tryTimeout": "00:01:00",
                "delay": "00:00:00.80",
                "maxDelay": "00:01:00",
                "maxRetries": 3
            },
            "prefetchCount": 0,
            "transportType": "amqpWebSockets",
            "webProxy": "https://proxyserver:8080",
            "autoCompleteMessages": true,
            "maxAutoLockRenewalDuration": "00:05:00",
            "maxConcurrentCalls": 16,
            "maxConcurrentSessions": 8,
            "maxMessageBatchSize": 1000,
            "minMessageBatchSize": 1,
            "maxBatchWaitTime": "00:00:30",
            "sessionIdleTimeout": "00:01:00",
            "enableCrossEntityTransactions": false
        }
    }
}

clientRetryOptions 设置仅适用于与服务总线服务的交互。 它们不影响函数执行的重试。 有关详细信息,请参阅重试

属性 默认 说明
mode Exponential 用于计算重试延迟的方法。 默认指数模式将根据一个回退策略来重试带延迟的尝试,该策略规定每次尝试都会增加重试前的等待时间。 Fixed 模式会按固定间隔重试,每个延迟的持续时间一致。
tryTimeout 00:01:00 每次尝试等待操作的最大持续时间。
delay 00:00:00.80 要在两次重试之间应用的延迟或回退因子。
maxDelay 00:01:00 允许出现在两次重试之间的最大延迟
maxRetries 3 将关联的操作视为失败之前的最大重试次数。
prefetchCount 0 获取或设置消息接收方可以同时请求的消息数。
transportType amqpTcp 用于与服务总线通信的协议和传输。 可用选项:amqpTcpamqpWebSockets
webProxy 不适用 用于通过 Web 套接字与服务总线进行通信的代理。 代理不能与 amqpTcp 传输一起使用。
autoCompleteMessages true 确定是否在成功执行函数后自动完成消息。应该用来替换 autoComplete 配置设置。
maxAutoLockRenewalDuration 00:05:00 自动续订消息锁的最长持续时间。 此设置仅适用于一次接收一条消息的函数。
maxConcurrentCalls 16 对于每个缩放实例,应该对回调发起的最大并发调用数。 默认情况下,Functions 运行时同时处理多条消息。 仅当触发器上的 isSessionsEnabled 属性或特性设置为 false 时,才应使用此设置。 此设置仅适用于一次接收一条消息的函数。
maxConcurrentSessions 8 每个缩放实例可以并发处理的最大会话数。 仅当触发器上的 isSessionsEnabled 属性或特性设置为 true 时,才应使用此设置。 此设置仅适用于一次接收一条消息的函数。
maxMessageBatchSize 1000 将传递给每个函数调用的消息的最大数量。 此设置仅适用于接收一批消息的函数。
minMessageBatchSize1 1 批中所需的最小消息数。 仅当函数接收多个消息时,最小值才适用,且必须小于 maxMessageBatchSize
不严格保证最小大小。 如果在 maxBatchWaitTime 内无法准备好整批,则将调度部分批。
maxBatchWaitTime1 00:00:30 在调用函数之前触发器应等待填充批的最大时间间隔。 仅当 minMessageBatchSize 大于 1 时才考虑等待时间,否则忽略。 如果在达到等待时间前可用消息数少于 minMessageBatchSize,则会使用部分批调用函数。 允许的最长等待时间为实体消息锁定持续时间的 50%,这意味着允许的等待时间最大值为 2 分 30 秒。 否则,可能会出现锁定异常。

注意:此间隔不能严格保证调用函数的确切时间。 由于计时器精度原因,可能存在很小的误差。
sessionIdleTimeout 不适用 当前活动会话等待某个消息被接收的最长时间。 在此时间过后,会话将被关闭,函数将尝试处理另一个会话。
enableCrossEntityTransactions false 是否启用在服务总线命名空间上跨多个实体的事务。

1 使用 minMessageBatchSizemaxBatchWaitTime 需要 v5.10.0 或更高版本的 Microsoft.Azure.WebJobs.Extensions.ServiceBus 包。

后续步骤