使用服务总线触发器响应来自服务总线队列或主题的消息。 从扩展版本 3.1.0 开始,可以在启用会话的队列或主题上触发。
有关设置和配置详细信息,请参阅概述。
示例
C#
以下示例演示了读取消息元数据并记录服务总线队列消息的 C# 函数:
[FunctionName("ServiceBusQueueTriggerCSharp")]
public static void Run(
[ServiceBusTrigger("myqueue", Connection = "ServiceBusConnection")]
string myQueueItem,
Int32 deliveryCount,
DateTime enqueuedTimeUtc,
string messageId,
ILogger log)
{
log.LogInformation($"C# ServiceBus queue trigger function processed message: {myQueueItem}");
log.LogInformation($"EnqueuedTimeUtc={enqueuedTimeUtc}");
log.LogInformation($"DeliveryCount={deliveryCount}");
log.LogInformation($"MessageId={messageId}");
}
C# 脚本
以下示例演示 function.json 文件中的一个服务总线触发器绑定以及使用该绑定的 C# 脚本函数。 此函数将读取消息元数据并记录服务总线队列消息。
下面是 function.json 文件中的绑定数据:
{
"bindings": [
{
"queueName": "testqueue",
"connection": "MyServiceBusConnection",
"name": "myQueueItem",
"type": "serviceBusTrigger",
"direction": "in"
}
],
"disabled": false
}
C# 脚本代码如下所示:
using System;
public static void Run(string myQueueItem,
Int32 deliveryCount,
DateTime enqueuedTimeUtc,
string messageId,
TraceWriter log)
{
log.Info($"C# ServiceBus queue trigger function processed message: {myQueueItem}");
log.Info($"EnqueuedTimeUtc={enqueuedTimeUtc}");
log.Info($"DeliveryCount={deliveryCount}");
log.Info($"MessageId={messageId}");
}
Java
以下 Java 函数使用 Java 函数运行时库中的 @ServiceBusQueueTrigger 注释来说明服务总线队列触发器的配置。 此函数获取放置在队列上的消息,然后将其添加到日志。
@FunctionName("sbprocessor")
public void serviceBusProcess(
@ServiceBusQueueTrigger(name = "msg",
queueName = "myqueuename",
connection = "myconnvarname") String message,
final ExecutionContext context
) {
context.getLogger().info(message);
}
将消息添加到服务总线主题时,也可触发 Java 函数。 以下示例使用 @ServiceBusTopicTrigger 注释来说明触发器配置。
@FunctionName("sbtopicprocessor")
public void run(
@ServiceBusTopicTrigger(
name = "message",
topicName = "mytopicname",
subscriptionName = "mysubscription",
connection = "ServiceBusConnection"
) String message,
final ExecutionContext context
) {
context.getLogger().info(message);
}
JavaScript
以下示例演示 function.json 文件中的一个服务总线触发器绑定以及使用该绑定的 JavaScript 函数。 此函数将读取消息元数据并记录服务总线队列消息。
下面是 function.json 文件中的绑定数据:
{
"bindings": [
{
"queueName": "testqueue",
"connection": "MyServiceBusConnection",
"name": "myQueueItem",
"type": "serviceBusTrigger",
"direction": "in"
}
],
"disabled": false
}
JavaScript 脚本代码如下所示:
module.exports = function(context, myQueueItem) {
context.log('Node.js ServiceBus queue trigger function processed message', myQueueItem);
context.log('EnqueuedTimeUtc =', context.bindingData.enqueuedTimeUtc);
context.log('DeliveryCount =', context.bindingData.deliveryCount);
context.log('MessageId =', context.bindingData.messageId);
context.done();
};
PowerShell
下面的示例演示了文件 function.js上 的服务总线触发器绑定,以及使用绑定的 PowerShell 函数 。
下面是 function.json 文件中的绑定数据:
{
"bindings": [
{
"name": "mySbMsg",
"type": "serviceBusTrigger",
"direction": "in",
"topicName": "mytopic",
"subscriptionName": "mysubscription",
"connection": "AzureServiceBusConnectionString"
}
]
}
下面是发送服务总线消息时运行的函数。
param([string] $mySbMsg, $TriggerMetadata)
Write-Host "PowerShell ServiceBus queue trigger function processed message: $mySbMsg"
Python
下面的示例演示如何通过触发器读取服务总线队列消息。
服务总线绑定在 "类型" 设置为的 function.js 中定义 serviceBusTrigger 。
{
"scriptFile": "__init__.py",
"bindings": [
{
"name": "msg",
"type": "serviceBusTrigger",
"direction": "in",
"queueName": "inputqueue",
"connection": "AzureServiceBusConnectionString"
}
]
}
_ _ Py 中的代码将参数声明为 func.ServiceBusMessage ,这允许您在函数中读取队列消息。
import azure.functions as func
import logging
import json
def main(msg: func.ServiceBusMessage):
logging.info('Python ServiceBus queue trigger processed message.')
result = json.dumps({
'message_id': msg.message_id,
'body': msg.get_body().decode('utf-8'),
'content_type': msg.content_type,
'expiration_time': msg.expiration_time,
'label': msg.label,
'partition_key': msg.partition_key,
'reply_to': msg.reply_to,
'reply_to_session_id': msg.reply_to_session_id,
'scheduled_enqueue_time': msg.scheduled_enqueue_time,
'session_id': msg.session_id,
'time_to_live': msg.time_to_live,
'to': msg.to,
'user_properties': msg.user_properties,
'metadata' : msg.metadata
})
logging.info(result)
特性和注释
C#
在 C# 类库中,请使用以下属性来配置服务总线触发器:
-
该特性的构造函数采用队列或者主题和订阅的名称。 在 Azure Functions 版本 1.x 中,还可以指定连接的访问权限。 如果未指定访问权限,则默认为
Manage。 有关详细信息,请参阅触发器 - 配置部分。下面是一个示例,演示了用于字符串参数的属性:
[FunctionName("ServiceBusQueueTriggerCSharp")] public static void Run( [ServiceBusTrigger("myqueue")] string myQueueItem, ILogger log) { ... }由于未定义
Connection属性,因此 Azure Functions 将查找名为AzureWebJobsServiceBus的应用设置,这是服务总线连接字符串的默认名称。 还可以设置Connection属性来指定应用程序设置(其中包含要使用的服务总线连接字符串)的名称,如以下示例中所示:[FunctionName("ServiceBusQueueTriggerCSharp")] public static void Run( [ServiceBusTrigger("myqueue", Connection = "ServiceBusConnection")] string myQueueItem, ILogger log) { ... }有关完整示例,请参阅触发器 - 示例。
-
提供另一种方式来指定要使用的服务总线帐户。 构造函数采用包含服务总线连接字符串的应用设置的名称。 可以在参数、方法或类级别应用该特性。 以下示例演示类级别和方法级别:
[ServiceBusAccount("ClassLevelServiceBusAppSetting")] public static class AzureFunctions { [ServiceBusAccount("MethodLevelServiceBusAppSetting")] [FunctionName("ServiceBusQueueTriggerCSharp")] public static void Run( [ServiceBusTrigger("myqueue", AccessRights.Manage)] string myQueueItem, ILogger log) { ... }
要使用的服务总线帐户按以下顺序确定:
ServiceBusTrigger特性的Connection属性。- 作为
ServiceBusTrigger特性应用到同一参数的ServiceBusAccount特性。 - 应用到函数的
ServiceBusAccount特性。 - 应用到类的
ServiceBusAccount特性。 - “AzureWebJobsServiceBus”应用设置。
C# 脚本
C# 脚本不支持特性。
Java
使用 ServiceBusQueueTrigger 注释可以创建在创建服务总线队列消息时要运行的函数。 可用的配置选项包括队列名称和连接字符串名称。
使用 ServiceBusTopicTrigger 注释可以指定主题和订阅,以便以触发函数的数据为目标。
有关更多详细信息,请参阅触发器示例。
JavaScript
JavaScript 不支持特性。
PowerShell
PowerShell 不支持特性。
Python
Python 不支持特性。
配置
下表解释了在 function.json 文件和 ServiceBusTrigger 特性中设置的绑定配置属性。
| function.json 属性 | Attribute 属性 | 说明 |
|---|---|---|
| type | 不适用 | 必须设置为“serviceBusTrigger”。 在 Azure 门户中创建触发器时,会自动设置此属性。 |
| direction | 不适用 | 必须设置为“in”。 在 Azure 门户中创建触发器时,会自动设置此属性。 |
| name | 不适用 | 变量的名称,表示函数代码中的队列或主题消息。 |
| queueName | QueueName | 要监视的队列的名称。 仅在监视队列的情况下设置,不为主题设置。 |
| topicName | TopicName | 要监视的主题的名称。 仅在监视主题的情况下设置,不为队列设置。 |
| subscriptionName | SubscriptionName | 要监视的订阅的名称。 仅在监视主题的情况下设置,不为队列设置。 |
| 连接 | Connection | 应用设置的名称,包含要用于此绑定的服务总线连接字符串。 如果应用设置名称以“AzureWebJobs”开头,则只能指定该名称的余下部分。 例如,如果将 connection 设为“MyServiceBus”,Functions 运行时会查找名为“AzureWebJobsMyServiceBus”的应用设置。 如果将 connection 留空,函数运行时将使用名为“AzureWebJobsServiceBus”的应用设置中的默认服务总线连接字符串。若要获取连接字符串,请执行获取管理凭据中显示的步骤。 必须是服务总线命名空间的连接字符串,不限于特定的队列或主题。 |
| accessRights | Access | 连接字符串的访问权限。 可用值为 manage 和 listen。 默认值是 manage,其指示 connection 具有“管理”权限。 如果使用不具有“管理”权限的连接字符串,请将 accessRights 设置为“listen”。 否则,Functions 运行时可能会在尝试执行需要管理权限的操作时失败。 在 Azure Functions 版本 2.x 及更高版本中,此属性不可用,因为最新版本的服务总线 SDK 不支持管理操作。 |
| isSessionsEnabled | IsSessionsEnabled | 如果连接到会话感知队列或订阅,则为 true。 否则为 false(默认值)。 |
在本地进行开发时,应用设置将取 local.settings.json 文件的值。
使用情况
C#
以下参数类型可用于队列或主题消息:
string- 如果消息是文本。byte[]- 适用于二进制数据。- 自定义类型 - 如果消息包含 JSON,Azure Functions 会尝试反序列化 JSON 数据。
BrokeredMessage- 提供带 BrokeredMessage.GetBody<T>() 方法的反序列化消息。MessageReceiver- 用于接收和确认来自消息容器的消息(当autoComplete设置为false时为必需)
这些参数类型适用于 Azure Functions 版本 1.x;对于 2.x 及更高版本,请使用 Message 而非 BrokeredMessage。
C# 脚本
以下参数类型可用于队列或主题消息:
string- 如果消息是文本。byte[]- 适用于二进制数据。- 自定义类型 - 如果消息包含 JSON,Azure Functions 会尝试反序列化 JSON 数据。
BrokeredMessage- 提供带 BrokeredMessage.GetBody<T>() 方法的反序列化消息。
这些参数仅适用于 Azure Functions 版本 1.x;对于 2.x 及更高版本,请使用 Message 而非 BrokeredMessage。
Java
可以通过 ServiceBusQueueMessage 或 ServiceBusTopicMessage 参数获取传入的服务总线消息。
JavaScript
使用 context.bindings.<name from function.json> 访问队列或主题消息。 服务总线消息作为字符串或 JSON 对象传递到函数中。
PowerShell
可以通过在 " function.js上 的" 文件名 "属性中配置的参数来使用服务总线实例。
Python
队列消息可通过类型化为的参数提供给函数 func.ServiceBusMessage 。 服务总线消息作为字符串或 JSON 对象传递到函数中。
有害消息
无法在 Azure Functions 中控制或配置有害消息处理。 服务总线处理有害消息本身。
PeekLock 行为
Functions 运行时以 PeekLock 模式接收消息。 如果函数成功完成,则对此消息调用 Complete;如果函数失败,则调用 Abandon。 如果函数的运行时间长于 PeekLock 超时时间,则只要该函数正在运行,就会自动续订锁定。
maxAutoRenewDuration 可在 host.json 中配置,它映射到 OnMessageOptions.MaxAutoRenewDuration。 根据服务总线文档,此设置所允许的最长时间为 5 分钟,而你可以将 Functions 时间限制从默认值 5 分钟增加到 10 分钟。 对于服务总线函数,你不会那么做,因为会超出服务总线续订限制。
消息元数据
服务总线触发器提供了几个元数据属性。 这些属性可在其他绑定中用作绑定表达式的一部分,或者用作代码中的参数。 以下属性是 Message 类的成员。
| 属性 | 类型 | 说明 |
|---|---|---|
ContentType |
string |
发送方和接收方用于实现应用程序特定逻辑的内容类型标识符。 |
CorrelationId |
string |
相关 ID。 |
DeadLetterSource |
string |
死信源。 |
DeliveryCount |
Int32 |
传递次数。 |
EnqueuedTimeUtc |
DateTime |
排队时间 (UTC)。 |
ExpiresAtUtc |
DateTime |
到期时间 (UTC)。 |
Label |
string |
应用程序特定的标签。 |
MessageId |
string |
服务总线可用于标识重复消息的用户定义值(如果启用)。 |
MessageReceiver |
MessageReceiver |
服务总线消息接收器。 可以用于放弃、完成消息或将消息放入死信队列。 |
MessageSession |
MessageSession |
专用于已启用会话的队列和主题的消息接收器。 |
ReplyTo |
string |
对队列地址的回复。 |
SequenceNumber |
long |
服务总线分配给消息的唯一编号。 |
To |
string |
发送到地址。 |
UserProperties |
IDictionary<string, object> |
由发送方设置的属性。 |
请参阅在本文的前面部分使用这些属性的代码示例。
后续步骤
历史资料。此文对应 2022-08-12 的中文文档快照,适用产品版本和命令行为以原文为准。
来源与署名:Microsoft 和文档贡献者(原始作者元数据 craigshoemaker)。固定版本原文。文档采用 CC BY 4.0,示例代码采用 MIT 授权。本站将 Markdown 转为 HTML,规范化链接,移除外部媒体和导航标记。
