通过

Azure Functions 的 Azure 服务总线绑定

  • 项目

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

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

安装扩展

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

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

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

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

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

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

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

通过安装 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) 类型。
ServiceBusReceivedMessage1 消息对象。

绑定到ServiceBusReceivedMessage时，还可以选择包含 ServiceBusMessageActions1,2 类型的参数来执行消息解决作。

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

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

绑定到ServiceBusReceivedMessage[]时，还可以选择包含 ServiceBusMessageActions1,2 类型的参数来执行消息解决作。

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

2 使用时，将ServiceBusMessageActions的属性设置为 AutoCompleteMessages。 这可以防止运行时在成功调用函数后尝试完成消息。

服务总线输出绑定

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

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

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

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

对于其他输出方案，请直接在 Azure.Messaging.ServiceBus 中创建和使用 ServiceBusClient 和其他类型的服务总线。 有关使用依赖项注入从 Azure SDK 创建客户端类型的示例，请参阅 “注册 Azure 客户端 ”。

SDK 绑定类型

Azure 服务总线的 SDK 类型为预览版。 按照 适用于服务总线的 Python SDK 绑定示例 开始使用 Python 中的服务总线的 SDK 类型。

重要

使用 SDK 类型绑定需要 Python v2 编程模型。

捆绑 参数类型 示例
ServiceBus 触发器 ServiceBusReceivedMessage ServiceBusReceivedMessage

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 设置仅适用于与服务总线服务的交互。 它们不影响函数执行的重试。 有关详细信息，请参阅重试。

属性 默认 说明
模式 Exponential 用于计算重试延迟的方法。 默认指数模式将根据一个回退策略来重试带延迟的尝试，该策略规定每次尝试都会增加重试前的等待时间。 Fixed 模式会按固定间隔重试，每个延迟的持续时间一致。
tryTimeout 00:01:00 每次尝试等待操作的最大持续时间。
延迟 00:00:00.80 要在两次重试之间应用的延迟或回退因子。
maxDelay 00:01:00 允许出现在两次重试之间的最大延迟
maxRetries 3 将关联的操作视为失败之前的最大重试次数。
prefetchCount 0 获取或设置消息接收方可以同时请求的消息数。
运输类型 amqpTcp 用于与服务总线通信的协议和传输。 可用选项：amqpTcp、amqpWebSockets
webProxy 不适用 用于通过 Web 套接字与服务总线进行通信的代理。 代理不能与 amqpTcp 传输一起使用。
autoCompleteMessages true 确定是否在成功执行函数后自动完成消息。
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 使用 minMessageBatchSize 和 maxBatchWaitTime 需要 v5.10.0 或更高版本的 Microsoft.Azure.WebJobs.Extensions.ServiceBus 包。

后续步骤