Azure 事件网格事件架构

本文介绍了事件网格架构，它是一种专有、不可扩展且功能齐全的事件格式。事件网格仍支持此事件格式，并将继续支持它。但建议使用 CloudEvents 事件格式。如果使用的是使用事件网格格式的应用程序，则可以在 [CloudEvents] 部分中找到有用的信息，该部分介绍了事件网格和事件网格支持的 CloudEvents 格式之间转换。

本文详细介绍了事件网格格式的属性和架构。事件包含一组四个所需字符串属性。这些属性在任何发布服务器的所有事件中通用。数据对象具有特定于每个发布者的属性。对于系统主题，这些属性特定于资源提供程序，例如 Azure 存储或 Azure 事件中心。

事件源会将事件发送到数组中的 Azure 事件网格（其中可包含多个事件对象）。将事件发布到事件网格主题时，数组的总大小最大可为 1 MB。数组中的每个事件被限制为 1 MB。事件或数组超出大小限制时会收到响应“413 有效负载太大”。不过，操作以 64KB 为增量进行收费。因此，超过 64 KB 的事件会产生操作费用，就像它们是多个事件一样。例如，大小为 130KB 的事件产生的操作就像它是 3 个不同的事件一样。

事件网格会将事件发送给具有单个事件的数组中的订阅者。此行为在将来可能会更改。

可以在事件架构存储中找到事件网格事件的 JSON 架构和每个 Azure 发布服务器的数据负载。

注意

我们不会停用对事件网格事件架构的支持，但将来也不会进行任何重大改进。建议使用 CloudEvents 架构，该架构提供适用于所有协议的标准事件结构和元数据说明定义。有关详细信息，请参阅 CloudEvents v1.0 架构与 Azure 事件网格配合使用。

事件架构

以下示例显示所有事件发布者使用的属性：

[
  {
    "topic": string,
    "subject": string,
    "id": string,
    "eventType": string,
    "eventTime": string,
    "data":{
      object-unique-to-each-publisher
    },
    "dataVersion": string,
    "metadataVersion": string
  }
]

例如，为 Azure Blob 存储事件发布的架构是：

[
  {
    "topic": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/contosorg/providers/Microsoft.Storage/storageAccounts/contosostorage",
    "subject": "/blobServices/default/containers/testcontainer/blobs/dataflow.jpg",
    "eventType": "Microsoft.Storage.BlobCreated",
    "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
    "data": {
      "api": "PutBlob",
      "clientRequestId": "bbbbbbbb-1111-2222-3333-cccccccccccc",
      "requestId": "cccccccc-2222-3333-4444-dddddddddddd",
      "eTag": "0x8DD15A69488FE5A",
      "contentType": "image/jpeg",
      "contentLength": 52577,
      "blobType": "BlockBlob",
      "accessTier": "Default",
      "url": "https://contosostorage.blob.core.chinacloudapi.cn/testcontainer/dataflow.jpg",
      "sequencer": "0000000000000000000000000003A13C00000000007da85d",
      "storageDiagnostics": {
        "batchId": "9d292d9f-e006-00a5-008f-47b300000000"
      }
    },
    "dataVersion": "",
    "metadataVersion": "1",
    "eventTime": "2024-12-06T03:32:15.7238874Z"
  }
]

注意

数据对象对于每个事件发布者都是唯一的。有关系统主题，请参阅事件架构存储或相应的系统主题文档，以查看每个发布者的确切架构。对于自定义主题，发布者定义数据对象的结构。

事件属性

所有事件均具有以下相同的顶级数据：

属性	类型	必需	说明
`topic`	字符串	否，但如果包含，则必须与事件网格主题 Azure 资源管理器 ID 完全匹配。如果不包含，事件网格会标记到事件上。	事件源的完整资源路径。此字段不可写入。事件网格提供此值。
`subject`	字符串	是	事件主题的发布者定义路径。
`eventType`	字符串	是	此事件源的一个注册事件类型。
EventTime	字符串	是	基于提供程序 UTC 时间的事件生成时间。
`id`	字符串	是	事件的唯一标识符。
`data`	对象	是	特定于资源提供程序的事件数据。
`dataVersion`	字符串	否，但将使用空值进行标记。	数据对象的架构版本。发布者定义架构版本。
`metadataVersion`	字符串	不是必需的，但如果包含，则必须与事件网格架构 `metadataVersion` 完全匹配（目前仅为 `1`）。如果不包含，事件网格会标记到事件上。	事件元数据的架构版本。事件网格定义顶级属性的架构。事件网格提供此值。

若要了解数据对象中的属性，请参阅系统主题一节中的文章。

对于自定义主题，事件发布者确定数据对象。顶级数据应具有与标准资源所定义事件相同的字段。

将事件发布到自定义主题时，可为事件创建主题，便于订阅者们了解他们是否对该事件感兴趣。订阅者使用主题来筛选和路由事件。请考虑为事件发生的位置提供路径，以便订阅者可根据该路径的片段进行筛选。通过路径，订阅者可精确或宽泛地筛选事件。例如，如果在主题中提供一个由三个片段构成的路径（如 /A/B/C），订阅者可根据第一个片段 /A 进行筛选，获取范围较宽泛的一组事件。这些订阅者会获取主题为 /A/B/C 或 /A/D/E 这样的事件。其他订阅者可通过 /A/B 进行筛选，这样可以获取范围更精确的一组事件。

有时，需要提供有关发生事件更详细的信息才能查找到所需主题。例如，将文件添加到容器时，“存储帐户”发布服务器提供主题 /blobServices/default/containers/<container-name>/blobs/<file>。订阅者可以按路径 /blobServices/default/containers/<container-name>/ 进行筛选，获取有关该容器而非存储帐户中其他容器的所有事件。订阅者还可通过使用后缀 .txt 进行筛选或路由，来达到仅处理文本文件的目的。

CloudEvents

建议使用 CloudEvents 事件格式。 Azure 事件网格将会继续投资于至少与 CloudEvents JSON 格式相关的功能。鉴于某些事件源（如 Azure 服务）使用事件网格的格式，下表将有助于你了解将 CloudEvents 和事件网格格式用作主题中的输入架构以及事件订阅中的输出架构时支持的转换。将 CloudEvents 用作输入架构时，无法使用事件网格输出架构，因为 CloudEvents 支持事件网格架构不支持的扩展属性。

输入架构	输出架构
CloudEvents 格式	CloudEvents 格式
事件网格格式	CloudEvents 格式
事件网格格式	事件网格格式

支持的架构版本

事件网格当前支持以下架构版本：

事件网格架构：版本 1.0
CloudEvents 架构：版本 1.0，遵循 CloudEvents v1.0 规范

后续步骤

有关 Azure 事件网格的简介，请参阅什么是事件网格？
有关创建 Azure 事件网格订阅的详细信息，请参阅事件网格订阅架构。

上次更新时间为 2025-11-19