为 Azure 服务总线队列和订阅启用消息过期死信
Azure 服务总线队列和主题订阅提供名为“死信队列”(DLQ) 的辅助子队列。 死信队列不需要显式创建,并且不能删除或独立于主实体进行管理。 死信队列的用途是存放无法传递给任何接收方的消息或无法处理的消息。 有关详细信息,请参阅服务总线死信队列概述。 本文介绍为服务总线队列和订阅启用死信的不同方式。
使用 Azure 门户
在 Azure 门户中创建队列或主题订阅时,请选择“为消息过期启用死信”,如以下示例中所示。
创建启用死信的队列
创建启用死信的订阅
更新现有队列消息过期的死信设置
在服务总线队列的“概述”页面上,选择消息过期死信设置的当前值。 以下示例返回的当前值为“禁用”。 你可以在弹出窗口中启用或禁用消息过期死信。
更新现有订阅消息过期的死信设置
在服务总线订阅的“概述”页面上,选择消息过期死信设置的当前值。 以下示例返回的当前值为“禁用”。 你可以在弹出窗口中启用或禁用消息过期死信。
使用 Azure CLI
若要创建已启用消息过期死信的队列,请使用 az servicebus queue create
命令将 --enable-dead-lettering-on-message-expiration
设置为 true
。
az servicebus queue create \
--resource-group myresourcegroup \
--namespace-name mynamespace \
--name myqueue \
--enable-dead-lettering-on-message-expiration true
若要为现有队列启用消息过期死信设置,请使用 az servicebus queue update
命令将 --enable-dead-lettering-on-message-expiration
设置为 true
。
az servicebus queue update \
--resource-group myresourcegroup \
--namespace-name mynamespace \
--name myqueue \
--enable-dead-lettering-on-message-expiration true
若要创建已启用消息过期死信的主题订阅,请使用 az servicebus topic subscription create
命令将 --enable-dead-lettering-on-message-expiration
设置为 true
。
az servicebus topic subscription create \
--resource-group myresourcegroup \
--namespace-name mynamespace \
--topic-name mytopic \
--name mysubscription \
--enable-dead-lettering-on-message-expiration true
若要为主题订阅启用消息过期死信设置,请使用 az servicebus topic subscription update
命令将 --enable-dead-lettering-on-message-expiration
设置为 true
。
az servicebus topic subscription update \
--resource-group myresourcegroup \
--namespace-name mynamespace \
--topic-name mytopic \
--name mysubscription \
--enable-dead-lettering-on-message-expiration true
注意
如果使用 --forward-dead-lettered-messages-to
参数指定队列或主题,服务总线会自动将死信消息转发到该队列或主题。 下面是一个示例:az servicebus queue create --resource-group mysbusrg --namespace-name mysbusns --name myqueue --enable-dead-lettering-on-message-expiration true --forward-dead-lettered-messages-to myqueue2
。
使用 Azure PowerShell
若要创建已启用消息过期死信的队列,请使用 New-AzServiceBusQueue
命令将 -DeadLetteringOnMessageExpiration
设置为 $True
。
New-AzServiceBusQueue -ResourceGroup myresourcegroup `
-NamespaceName mynamespace `
-QueueName myqueue `
-DeadLetteringOnMessageExpiration $True
若要为现有队列启用消息过期死信设置,请使用 Set-AzServiceBusQueue
命令,如下方示例中所示。
$queue=Get-AzServiceBusQueue -ResourceGroup myresourcegroup `
-NamespaceName mynamespace `
-QueueName myqueue
$queue.DeadLetteringOnMessageExpiration=$True
Set-AzServiceBusQueue -ResourceGroup myresourcegroup `
-NamespaceName mynamespace `
-QueueName myqueue `
-QueueObj $queue
若要创建已启用消息过期死信的主题订阅,请使用 New-AzServiceBusSubscription
命令将 -DeadLetteringOnMessageExpiration
设置为 $True
。
New-AzServiceBusSubscription -ResourceGroup myresourcegroup `
-NamespaceName mynamespace `
-TopicName mytopic `
-SubscriptionName mysubscription `
-DeadLetteringOnMessageExpiration $True
若要为现有订阅启用消息过期死信设置,请参阅下方示例。
$subscription=Get-AzServiceBusSubscription -ResourceGroup myresourcegroup `
-NamespaceName mynamespace `
-TopicName mytopic `
-SubscriptionName mysub
$subscription.DeadLetteringOnMessageExpiration=$True
Set-AzServiceBusSubscription -ResourceGroup myresourcegroup `
-NamespaceName mynamespace `
-Name mytopic `
-SubscriptionName mysub `
-SubscriptionObj $subscription
注意
如果使用 -ForwardDeadLetteredMessagesTo
参数指定队列或主题,事件网格会自动将死信消息转发到该队列或主题。
使用 Azure 资源管理器模板
若要创建已启用消息过期死信的队列,请在“队列属性”部分将 deadLetteringOnMessageExpiration
设置为 true
。 有关详细信息,请参阅 Microsoft.ServiceBus 命名空间/队列模板参考。
{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"parameters": {
"serviceBusNamespaceName": {
"type": "string",
"metadata": {
"description": "Name of the Service Bus namespace"
}
},
"serviceBusQueueName": {
"type": "string",
"metadata": {
"description": "Name of the Queue"
}
},
"location": {
"type": "string",
"defaultValue": "[resourceGroup().location]",
"metadata": {
"description": "Location for all resources."
}
}
},
"resources": [
{
"type": "Microsoft.ServiceBus/namespaces",
"apiVersion": "2018-01-01-preview",
"name": "[parameters('serviceBusNamespaceName')]",
"location": "[parameters('location')]",
"sku": {
"name": "Standard"
},
"properties": {},
"resources": [
{
"type": "Queues",
"apiVersion": "2017-04-01",
"name": "[parameters('serviceBusQueueName')]",
"dependsOn": [
"[resourceId('Microsoft.ServiceBus/namespaces', parameters('serviceBusNamespaceName'))]"
],
"properties": {
"deadLetteringOnMessageExpiration": true
}
}
]
}
]
}
若要创建已启用消息过期死信的主题订阅,请在“队列属性”部分将 deadLetteringOnMessageExpiration
设置为 true
。 有关详细信息,请参阅 Microsoft.ServiceBus 命名空间/主题/订阅模板参考。
{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"parameters": {
"service_BusNamespace_Name": {
"type": "string",
"metadata": {
"description": "Name of the Service Bus namespace"
}
},
"serviceBusTopicName": {
"type": "string",
"metadata": {
"description": "Name of the Topic"
}
},
"serviceBusSubscriptionName": {
"type": "string",
"metadata": {
"description": "Name of the Subscription"
}
},
"location": {
"type": "string",
"defaultValue": "[resourceGroup().location]",
"metadata": {
"description": "Location for all resources."
}
}
},
"resources": [
{
"apiVersion": "2018-01-01-preview",
"name": "[parameters('service_BusNamespace_Name')]",
"type": "Microsoft.ServiceBus/namespaces",
"location": "[parameters('location')]",
"sku": {
"name": "Standard"
},
"properties": {},
"resources": [
{
"apiVersion": "2017-04-01",
"name": "[parameters('serviceBusTopicName')]",
"type": "topics",
"dependsOn": [
"[resourceId('Microsoft.ServiceBus/namespaces/', parameters('service_BusNamespace_Name'))]"
],
"properties": {
"maxSizeInMegabytes": 1024
},
"resources": [
{
"apiVersion": "2017-04-01",
"name": "[parameters('serviceBusSubscriptionName')]",
"type": "Subscriptions",
"dependsOn": [
"[parameters('serviceBusTopicName')]"
],
"properties": {
"deadLetteringOnMessageExpiration": true
}
}
]
}
]
}
]
}
注意
如果为 forwardDeadLetteredMessagesTo
属性指定队列或主题,事件网格会自动将死信消息转发到该队列或主题。
后续步骤
尝试采用所选语言的示例,了解 Azure 服务总线功能。
- 适用于 .NET(最新)的 Azure 服务总线客户端库示例
- 适用于 Java(最新)的 Azure 服务总线客户端库示例
- 适用于 Python 的 Azure 服务总线客户端库示例
- 适用于 JavaScript 的 Azure 服务总线客户端库示例
- 适用于 TypeScript 的 Azure 服务总线客户端库示例
查找早期 .NET 和 Java 客户端库示例:
注意
2026 年 9 月 30 日,我们将停用 Azure 服务总线 SDK 库 WindowsAzure.ServiceBus、Microsoft.Azure.ServiceBus 和 com.microsoft.azure.servicebus,这些库不符合 Azure SDK 准则。 我们还将结束对 SBMP 协议的支持,因此在 2026 年 9 月 30 日之后,你将无法再使用此协议。 请在该日期之前迁移到最新的 Azure SDK 库,新库提供了关键安全更新和改进功能。
尽管旧库在 2026 年 9 月 30 日之后仍可使用,但它们将不再获得 Azure 的官方支持和更新。 有关详细信息,请参阅支持停用公告。