你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Azure 事件网格中命名空间主题事件订阅的死信

2023-11-16

本文介绍命名空间主题的事件订阅的死信。死信处理过程会移动无法发送或处理到支持目标的事件订阅中的事件。目前，Azure Blob 存储是唯一受支持的死信目标。

下面是一些会发生死信的情况。

有害消息（拉取传递和推送传递）。
使用者应用程序在锁定（拉取）或保留期过期（拉取和推送）之前无法处理事件。
已达到允许重试事件（推送）的最大传递尝试次数（拉取和推送）或时间。

死信事件以 CloudEvents JSON 格式（结构化内容和二进制内容模式）存储在 Azure Blob 存储中。

用例

下面是你可能希望在应用程序中使用死信功能的一些用例。

你可能想要解除冻结无法处理或传递的事件，以便可以对这些事件进行预期的处理。解除冻结意味着将事件流回到事件网格中，以便现在按最初意图或目前认为适合的方式发送死信事件。例如，你可能会判定某些死信事件可能不是要放回数据管道的关键业务因素，因此这些事件不会解除冻结。
你可能想要存档事件，以便稍后可以读取和分析事件以进行审核。
你可能想要将死信事件发送到数据存储或专用工具，这些工具可提供更简单的用户界面，以更快地分析死信事件。

死信格式

存储死信事件时使用的格式是 CloudEvents JSON 格式。死信会保留事件的架构和格式。但除了原始发布的事件外，死信事件还会保留额外的元数据信息。

brokerProperties：描述导致事件成为死信的错误条件的元数据。此信息会始终存在。此元数据是使用键名称为 brokerProperties的对象描述的。
- deadletterreason - 事件成为死信的原因。
- deliveryattempts - 事件成为死信前的传递尝试次数。
- deliveryresult - 服务上次尝试传递事件期间的最后一个结果。
- publishutc - 事件网格保留和接受事件（例如 HTTP 200 OK）的 UTC 时间。
- deliveryattemptutc - 上次传递尝试的 UTC 时间。

customDeliveryProperties - 要与每个传出 HTTP 推送传递请求一起发出的事件订阅上配置的标头（自定义推送传递属性）。这些自定义属性中的一个或多个可能存在于持久化死信 JSON 中。不会存储标识为机密的自定义属性。此元数据是使用键名称为 customDeliveryProperties 的单独对象来描述的。该对象中的属性键名称及其值与在事件订阅中设置的内容完全相同。下面是一个示例：

Custom-Header-1: value1
Custom-Header-2: 32

它们使用以下对象保留在 Blob 中：

"customDeliveryProperties" : {
    "custom-header-1": "value1",
    "custom-header-2": "34"
}

持久化死信事件 JSON 为：

{
    "event": {
        "specversion": "1.0",
        "type": "com.example.someevent",
        "source": "/mycontext",
        "id": "A234-1234-1234",
        "time": "2018-04-05T17:31:00Z",
        "comexampleextension1": "value",
        "comexampleothervalue": 5,
        "datacontenttype": "application/json",
        "data": {
            // Event's objects/properties
        }
    },
    "customDeliveryProperties": {
        "custom-header-1": "value1",
        "custom-header-2": "34"
    },
    "deadletterProperties": {
        "deadletterreason": "Undeliverable due to client error",
        "deliveryattempts": 3,
        "deliveryresult": "Unauthorized",
        "publishutc": "2023-06-19T23:28:08.3063899Z",
        "deliveryattemptutc": "2023-06-09T23:28:08.3220145Z"
    }
}

死信事件可以按 CloudEvents 结构化模式或二进制模式存储。

使用 CloudEvents 结构化模式发布的事件

包含在 CloudEvents 结构化模式下发布的事件：

POST / HTTP/1.1
HOST jfgnspsc2.eastus-1.eventgrid.azure.net/topics/mytopic1
content-type: application/cloudevents+json

{
    "specversion": "1.0",
    "type": "com.example.someevent",
    "source": "/mycontext",
    "id": "A234-1234-1234",
    "time": "2018-04-05T17:31:00Z",
    "comexampleextension1": "value",
    "comexampleothervalue": 5,
    "datacontenttype": "application/json",
    "data": {
        // json event object goes here        
    }
}

在推送事件订阅上配置的以下自定义传递属性。

Custom-Header-1: value1
Custom-Header-1: 34

事件成为死信后，使用以下 JSON 格式内容在 Azure Blob 存储中创建的 Blob：

{
    "specversion": "1.0",
    "type": "com.example.someevent",
    "source": "/mycontext",
    "id": "A234-1234-1234",
    "time": "2018-04-05T17:31:00Z",
    "comexampleextension1": "value",
    "comexampleothervalue": 5,
    "datacontenttype": "application/json",
    "data": {
        // Event's objects/properties
    },
    "customDeliveryProperties": {
        "custom-header-1": "value1",
        "custom-header-2": "34"
    },
    "deadletterProperties": {
        "deadletterreason": "Undeliverable due to client error",
        "deliveryattempts": 3,
        "deliveryresult": "Unauthorized",
        "publishutc": "2023-06-19T23:28:08.3063899Z",
        "deliveryattemptutc": "2023-06-09T23:28:08.3220145Z"
    }
}

使用 CloudEvents 二进制模式发布的事件

包含在 CloudEvents 二进制模式下发布的事件：

POST / HTTP/1.1
HOST jfgnspsc2.eastus-1.eventgrid.azure.net/topics/mytopic1
ce-specversion: 1.0
ce-type: com.example.someevent
ce-source: /mycontext
ce-id: A234-1234-1234
ce-time: 2018-04-05T17:31:00Z
ce-comexampleextension1: value
ce-comexampleothervalue: 5
content-type: application/vnd.apache.thrift.binary

<raw binary data according to encoding specs for media type application/vnd.apache.thrift.binary>

在推送事件订阅上配置的以下自定义传递属性。

Custom-Header-1: value1
Custom-Header-1: 34

在 Azure Blob 存储中创建的 Blob 采用以下 JSON 格式（与结构化模式相同）。此示例演示了当 HTTP 的 content-type 或 datacontenttype 引用二进制媒体类型时使用的上下文属性 data_base64 的用法。如果 content-type 或 datacontenttype 引用 JSON 格式的内容（必须是窗体 */json 或 */*+json），则将使用 data 而不是 data_base64。

{
    "event": {
        "specversion": "1.0",
        "type": "com.example.someevent",
        "source": "/mycontext",
        "id": "A234-1234-1234",
        "time": "2018-04-05T17:31:00Z",
        "comexampleextension1": "value",
        "comexampleothervalue": 5,
        "datacontenttype": "application/vnd.apache.thrift.binary",
        "data_base64": "...base64 - encoded of binary data encoded according to application / vnd.apache.thrift.binary specs..."
    },
    "customDeliveryProperties": {
        "Custom-Header-1": "value1",
        "Custom-Header-2": "34"
    },
    "deadletterProperties": {
        "deadletterreason": "Undeliverable due to client error",
        "deliveryattempts": 3,
        "deliveryresult": "Unauthorized",
        "publishutc": "2023-06-19T23:28:08.3063899Z",
        "deliveryattemptutc": "2023-06-09T23:28:08.3220145Z"
    }
}

Blob 名称和文件夹位置

Blob 是一个 JSON 文件，其文件名是全局唯一标识符 (GUID)。例如 480b2295-0c38-40d0-b25a-f34b30aac1a9.json。单个 Blob 中可以包含一个或多个事件。

文件夹结构如下所示：<container_name>/<namespace_name>/<topic_name>/<event_subscription_name>/<year>/<month>/<day>/<UTC_hour>。例如：/<mycontainer/mynamespace/mytopic/myeventsubscription/2023/9/23/2/480b2295-0c38-40d0-b25a-f34b30aac1a9.json。

死信重试逻辑

你可能希望有权在 Azure 存储中断后不久访问死信事件，以便可以尽快处理这些死信。重试计划将遵循简单的逻辑，并且不可由你配置。

10 秒
1 分钟
5 分钟

第一次 5 分钟重试后，服务在达到最大重试期前将每隔 5 分钟重试一次。最大重试期为 2 天，并且可在事件订阅的事件订阅属性 deliveryRetryPeriodInDays 中配置，以先到者为准。如果事件在最大重试期后未成功存储在 Blob 上，则会删除该事件，并将其报告为失败的死信事件。

如果死信重试逻辑在事件订阅中配置的生存时间事件保留期之前开始，并且剩余生存时间小于所配置的重试期（例如，事件仅剩余 4 小时，并且已为死信配置了 2 天的 deliverRetryPeriod），则中转站会在已配置的最大死信传递重试期内保留死信，以遵循重试逻辑。

配置死信

下面是在事件订阅上配置死信的步骤。

为命名空间启用托管标识。
向标识授予对 Azure 存储帐户的写入权限。使用 Azure 门户中存储帐户的“访问控制”页将命名空间的标识添加到存储 Blob 数据参与者角色。
按下面的部分所示配置死信。

使用 Resource Manager 模板

下面是一个示例资源管理器模板 JSON 代码片段。还可以使用系统分配的托管标识（SystemAssigned）。

{
    "deadLetterDestinationWithResourceIdentity": {
    "deliveryRetryPeriodInDays": 2,
    "endpointType": "StorageBlob",
    "StorageBlob": {
        "blobContainerName": "data",
        "resourceId": "/subscriptions/0000000000-0000-0000-0000-000000000000/resourceGroups/myresourcegroup/providers/Microsoft.Storage/storageAccounts/mystorageaccount"
    },
    "identity": {
        "type": "UserAssigned",
        "userAssignedIdentity": "/subscriptions/0000000000-0000-0000-0000-000000000000/resourceGroups/myresourcegroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myusermsi"
		}
	}
}

使用 Azure 门户

在创建事件订阅时，可以启用死信并对其进行配置，如下图所示。

显示“创建订阅”页面的屏幕截图，其中显示了死信设置。

对于现有订阅：

导航到命名空间主题的“事件订阅”页。
在左侧菜单中，选择“配置”。
选择“启用死信”以启用该功能。
选择包含存储死信事件的 Azure 存储帐户的 Azure 订阅。
选择保存带有死信事件的 Blob 的 Blob 容器。
要使用托管标识，对于托管标识类型，请选择要用于连接到存储帐户的托管标识类型，并对其进行配置。

后续步骤

有关事件网格的介绍，请参阅关于事件网格。
若要开始使用命名空间主题，请参阅使用命名空间主题发布事件。