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

Azure 事件网格命名空间概念

项目
11/16/2023

本文介绍与命名空间主题相关的主要概念和功能。

事件

事件是完全描述系统中所发生情况的最少量信息。我们经常将事件称为离散事件，因为它代表了有关系统的明确独立事实，提供可操作的见解。每个事件具有通用信息，例如事件的 source、事件发生的 time 和唯一标识符。每个事件还有一个 type，这通常是用于描述使用事件的公告类型的唯一标识符。

例如，与在 Azure 存储中创建的有关新文件的事件将包含有关该文件的详细信息，如 lastTimeModified 值。事件中心事件具有 Capture 文件的 URL。订单微服务中有关新订单的事件可能具有一个 orderId 属性，以及一个表示订单状态的 URL 属性。其他事件类型的例子还包括：com.yourcompany.Orders.OrderCreated、org.yourorg.GeneralLedger.AccountChanged、io.solutionname.Auth.MaximumNumberOfUserLoginAttemptsReached。

下面是一个示例事件：

{
    "specversion" : "1.0",
    "type" : "com.yourcompany.order.created",
    "source" : "/orders/account/123",
    "subject" : "O-28964",
    "id" : "A234-1234-1234",
    "time" : "2018-04-05T17:31:00Z",
    "comexampleextension1" : "value",
    "comexampleothervalue" : 5,
    "datacontenttype" : "application/json",
    "data" : {
       "orderId" : "O-28964",
       "URL" : "https://com.yourcompany/orders/O-28964"
    }
}

另一种事件

用户社区也将携带数据点的消息（例如一条设备读取数据或 Web 应用程序页面单击操作）称为“事件”。通常会基于时间窗口分析这种事件，以得出见解并采取措施。在事件网格的文档中，我们将这种事件称为数据点、流数据或简称为遥测数据。此类型的事件（以及一些其他类型的消息）与事件网格的消息队列遥测传输 (MQTT) 中转站功能配合使用。

CloudEvents

事件网格命名空间主题接受符合云原生计算基础 (CNCF) 开放标准 CloudEvents 1.0 规范的事件，该规范使用 JSON 格式的 HTTP 协议绑定。 CloudEvent 是一种消息，包含要传递的内容（称为事件数据）和相关元数据。事件驱动体系结构中的事件数据通常携带宣告系统状态更改的信息。 CloudEvents 元数据由一组属性构成，这些属性提供有关消息的上下文信息，例如消息来源（源系统）、其类型等。符合 CloudEvents 规范的所有有效消息必须包含以下必需的上下文属性：

CloudEvents 规范还定义了使用事件网格时可包含的可选的和扩展上下文属性。

使用事件网格时，CloudEvents 是首选事件格式，因为它具有详细记录的用例（传输事件的模式、事件格式等）、扩展性和改进的互操作性。 CloudEvents 通过提供用于发布和使用事件的通用事件格式来提高互操作性。它允许使用统一的工具和标准方式来路由和处理事件。

CloudEvents 内容模式

CloudEvents 规范定义了三种内容模式：二进制、结构化和批量。

重要

在任何内容模式下均可交换文本（JSON、text/* 等）或二进制编码事件数据。二进制内容模式并不专用于发送二进制数据。

内容模式并非关于所使用的编码、二进制或文本，而是关于事件数据及其元数据的描述和交换方式。结构化内容模式使用单个结构，例如一个 JSON 对象，其 HTTP 有效负载中同时存在上下文属性和事件数据。二进制内容模式会将上下文属性（映射到 HTTP 标头）和事件数据（根据 Content-Type 中设置的媒体类型编码的 HTTP 有效负载）分隔。

CloudEvents 支持

此表显示了当前对 CloudEvents 规范的支持：

CloudEvents 内容模式	是否支持？
结构化 JSON	是
结构化 JSON 批处理	支持，用于发布事件
二进制	支持，用于发布事件

一个事件允许的最大大小为 1 MB。超过 64 KB 的事件以 64 KB 为增量计费。

结构化内容模式

CloudEvents 结构化内容模式下的消息其 HTTP 有效负载中同时存在上下文属性和事件数据。

重要

目前，事件网格支持 CloudEvents JSON 格式的 HTTP。

下面是结构化模式下使用 JSON 格式的 CloudEvents 示例。元数据（非“数据”的所有属性）和消息/事件数据（“数据”对象）都使用 JSON 来描述。我们的示例涵盖了所有必需的上下文属性以及一些可选属性（subject、time 和 datacontenttype）和扩展属性（comexampleextension1、comexampleothervalue）。

{
    "specversion" : "1.0",
    "type" : "com.yourcompany.order.created",
    "source" : "/orders/account/123",
    "subject" : "O-28964",
    "id" : "A234-1234-1234",
    "time" : "2018-04-05T17:31:00Z",
    "comexampleextension1" : "value",
    "comexampleothervalue" : 5,
    "datacontenttype" : "application/json",
    "data" : {
       "orderId" : "O-28964",
       "URL" : "https://com.yourcompany/orders/O-28964"
    }
}

可以将 JSON 格式与结构化内容结合使用，以发送非 JSON 值的事件数据。为此，执行以下步骤：

包含一个 datacontenttype 属性，该属性采用数据编码时采用的媒体类型。
如果该媒体类型采用文本格式（如 text/plain、text/csv 或 application/xml）进行编码，应结合使用 data 属性和一个包含通信内容作为值的 JSON 字符串。
如果该媒体类型表示二进制编码，应使用 data_base64 属性，其值是包含 BASE64 编码二进制值的 JSON 字符串。

例如，此 CloudEvent 携带采用 application/protobuf 编码的事件数据，用以交换 Protobuf 消息。

{
    "specversion" : "1.0",
    "type" : "com.yourcompany.order.created",
    "source" : "/orders/account/123",
    "id" : "A234-1234-1234",
    "time" : "2018-04-05T17:31:00Z",
    "datacontenttype" : "application/protobuf",
    "data_base64" : "VGhpcyBpcyBub3QgZW5jb2RlZCBpbiBwcm90b2J1ZmYgYnV0IGZvciBpbGx1c3RyYXRpb24gcHVycG9zZXMsIGltYWdpbmUgdGhhdCBpdCBpcyA6KQ=="
}

有关 data 或 data_base64 属性用法的详细信息，请参阅数据处理。

有关此内容模式的详细信息，请参阅 cloudEvents HTTP 结构化内容模式规范。

批量内容模式

事件网格当前支持在将 CloudEvents 发布到事件网格时使用 JSON 批量内容模式。此内容模式使用由结构化内容模式的 CloudEvents 填充的 JSON 数组。例如，应用程序可使用类似于以下的数组发布两个事件。同样，如果使用事件网格的数据平面 SDK，则此有效负载也属于要发送的内容：

[
    {
        "specversion": "1.0",
        "id": "E921-1234-1235",
        "source": "/mycontext",
        "type": "com.example.someeventtype",
        "time": "2018-04-05T17:31:00Z",
        "data": "some data"
    },
    {
        "specversion": "1.0",
        "id": "F555-1234-1235",
        "source": "/mycontext",
        "type": "com.example.someeventtype",
        "time": "2018-04-05T17:31:00Z",
        "data": {
            "somekey" : "value",
            "someOtherKey" : 9
        }
    }
]

有关详细信息，请参阅 CloudEvents 批量内容模式规范。

批处理

应用程序应在一个数组中统一批处理多个事件，以便通过单个发布请求获得更高的效率和更高的吞吐量。批最大可以为 1 MB，事件的最大大小为 1 MB。

二进制内容模式

二进制内容模式下的 CloudEvent 的上下文属性描述为 HTTP 标头。 HTTP 标头的名称是带有 ce- 前缀的上下文属性的名称。 Content-Type 标头反映事件数据编码时采用的媒体类型。

重要

使用二进制内容模式时，不能同时存在 ce-datacontenttype HTTP 标头。

重要

如果计划在使用二进制内容模式时包含自己的属性（即扩展属性），请确保其名称由 ASCII 字符中的小写字母（“a”到“z”）或数字（“0”到“9”）组成，且长度不超过 20 个字符。也即，用于命名 CloudEvents 上下文属性的命名约定比有效 HTTP 标头名的命名约定更严格。并非每个有效 HTTP 标头名都是有效的扩展属性名称。

HTTP 有效负载是根据 Content-Type 中的媒体类型编码的事件数据。

用于发布内容二进制模式的 CloudEvent 的 HTTP 请求如下例所示：

POST / HTTP/1.1
HOST mynamespace.eastus-1.eventgrid.azure.net/topics/mytopic
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/protobuf

Binary data according to protobuf encoding format. No context attributes are included.

何时使用 CloudEvents 的二进制或结构化内容模式

如果希望通过简单的方法来跨跃点和协议转发 CloudEvent，可以使用结构化内容模式。由于结构化内容模式下的 CloudEvent 同时包含了消息和元数据，客户端可轻松将其作为一个整体使用并将其转发到其他系统。

如果已知下游应用程序只需要消息而无需任何额外信息（即上下文属性），则可以使用二进制内容模式。虽然使用结构化内容模式时仍可从 CloudEvent 中获取事件数据（消息），但将数据置于 HTTP 有效负载中对于使用数据的应用程序而言会更轻松。例如，其他应用程序可以使用其他协议，并可能只需要核心消息而无需其元数据。事实上，元数据可能仅与紧接的第一个跃点相关。在这种情况下，将要交换的数据与其元数据分离有助于更轻松地处理和转发数据。

发布服务器

发布服务器是将事件发送到事件网格的应用程序。它可以是事件的来源应用程序，即事件源。使用命名空间主题时，你可以从自己的应用程序发布事件。

事件源

事件源即事件发生的位置。每个事件源支持一种或多种事件类型。例如，你的应用程序是你的系统定义的自定义事件的事件源。使用命名空间主题时，支持的事件源是你自己的应用程序。

命名空间

事件网格命名空间是以下资源的管理容器：

资源	支持的协议
命名空间主题	HTTP
主题空间	MQTT
客户端	MQTT
客户端组	MQTT
CA 证书	MQTT
权限绑定	MQTT

使用 Azure 事件网格命名空间，可以将相关资源归组，并将其作为 Azure 订阅中的单个单元进行管理。它提供唯一的完全限定的域名 (FQDN)。

命名空间公开两个终结点：

一个 HTTP 终结点，用于支持使用命名空间主题的一般消息传递要求。
一个 MQTT 终结点，用于使用 MQTT 的 IoT 消息传递或解决方案。

命名空间还提供与 DNS 集成的网络终结点。还提供一系列访问控制和网络集成管理功能，例如公共 IP 入口筛选和专用链接。它也是用于命名空间中所含资源的托管标识的容器。

以下进一步阐述了有关命名空间的一些要点：

命名空间是具有 tags 和 location 属性的受跟踪资源，创建后可在 resources.azure.com 上找到它。
命名空间的名称长度可为 3-50 个字符。它可以包含字母数字和连字符 (-)，不能包含空格。
该名称在每个区域中必须唯一。
当前支持的区域：美国中部、东亚、美国东部、美国东部 2、北欧、美国中南部、东南亚、阿联酋北部、西欧、美国西部 2、美国西部 3。

吞吐量单位

吞吐量单位 (TU) 定义命名空间中的入口和出口事件速率容量。有关详细信息，请参阅 Azure 事件网格配额和限制。

主题

主题包含已发布到事件网格的事件。通常会将主题资源用于相关事件的集合。命名空间中的主题通常称为命名空间主题。

命名空间主题

命名空间主题是在事件网格命名空间中创建的主题。应用程序将事件发布到 HTTP 命名空间终结点，该终结点指定了以逻辑方式包含已发布的事件的命名空间主题。在设计应用程序时，必须确定要创建多少个主题。对于相对较大的解决方案，请为相关事件的每个类别创建一个命名空间主题。例如，假设一个应用程序需要管理用户帐户，另一个应用程序需要管理客户订单。不太可能所有事件订阅者都需要这两个应用程序的事件。若要将问题分开，请创建两个命名空间主题：为每个应用程序各创建一个。让事件使用者根据其要求订阅主题。对于小型解决方案，可能希望将所有事件发送到单个主题。

命名空间主题支持拉取传递和推送传递。请参阅何时使用拉取传递或推送传递，以帮助确定拉取传递是否符合你的要求。

事件订阅

事件订阅是与单个主题关联的配置资源。此外，可以使用事件订阅来设置事件选择条件，以便基于主题中的整个事件集定义订阅服务器可用的事件集合。可以根据订阅者的要求筛选事件。例如，可以按事件类型筛选事件。如果将 JSON 对象作为数据属性的值，还可以定义事件数据属性的筛选条件。有关资源属性的详细信息，请查看事件网格 REST API 中的控制平面操作。

有关为命名空间主题创建订阅的示例，请参阅使用 CLI 和命名空间主题发布和使用消息。

注意

与在自定义、域、合作伙伴和系统主题（事件网格基本版）中使用的相比，命名空间主题下的事件订阅具有简化的资源模型。有关详细信息，请参阅“创建、查看和管理事件订阅”。

拉取传递

通过拉取传递，应用程序使用类似队列的语义连接到事件网格并读取消息。当应用程序连接到事件网格以使用事件时，可以控制事件使用速率及时间。当使用专用 IP 空间连接事件网格以读取事件时，要使用数据的应用程序还可使用专用终结点。

拉取传递支持在读取消息和控制消息状态时使用以下操作：接收、确认、释放、拒绝和续订锁定。有关详细信息，请参阅拉取传递概述。

使用拉取传递接收事件时的数据形状

使用拉取传递来传递事件时，事件网格包含一组对象，这些对象又包括 event 和 brokerProperties 对象。事件属性的值是在结构化内容模式下传递的 CloudEvent。 brokerProperties 对象包含与传递的 CloudEvent 关联的锁定令牌。以下 json 对象是一个接收操作的示例响应，该操作返回两个事件：

{
    "value": [
        {
            "brokerProperties": {
                "lockToken": "CiYKJDUwNjE4QTFFLUNDODQtNDZBQy1BN0Y4LUE5QkE3NjEwNzQxMxISChDXYS23Z+5Hq754VqQjxywE",
                "deliveryCount": 2
            },
            "event": {
                "specversion": "1.0",
                "id": "A234-1234-1235",
                "source": "/mycontext",
                "time": "2018-04-05T17:31:00Z",
                "type": "com.example.someeventtype",
                "data": "some data"
            }
        },
        {
            "brokerProperties": {
                "lockToken": "CiYKJDUwNjE4QTFFLUNDODQtNDZBQy1BN0Y4LUE5QkE3NjEwNzQxMxISChDLeaL+nRJLNq3/5NXd/T0b",
                "deliveryCount": 1
            },
            "event": {
                "specversion": "1.0",
                "id": "B688-1234-1235",
                "source": "/mycontext",
                "type": "com.example.someeventtype",
                "time": "2018-04-05T17:31:00Z",
                "data": {
                    "somekey" : "value",
                    "someOtherKey" : 9
                }
            }
        }
    ]
}

推送传递

使用推送传递时，事件网格会将事件发送到一个推送（传递模式）事件订阅中配置的目标。它提供了可靠的重试逻辑以防该目标无法接收事件。

重要

事件网格命名空间的推送传递目前支持以 Azure 事件中心为目标。以后事件网格命名空间会支持更多目标，包括“事件网格基本版”支持的所有目标。

事件中心事件传递

事件网格使用事件中心 SDK 通过 AMQP 将事件发送到事件中心。事件以字节数组的形式发送，其中有包含 CloudEvent 的数组中的每个元素。

推送和拉取传递

事件网格使用 HTTP 来支持推送和拉取事件传递。使用推送传递时，需要在事件订阅、Webhook 或 Azure 服务中定义一个目标，以便事件网格将事件发送到该目标。使用拉取传递时，订阅服务器应用程序将连接到事件网格以使用事件。事件网格命名空间中的主题支持拉取传递。

重要

支持将事件中心作为命名空间主题订阅的目标。在即将发布的版本中，事件网格命名空间支持事件网格基本版中当前支持的所有目标以及更多目标。

何时使用推送传递与拉取传递

以下一般指导原则可帮助你确定何时使用拉取传递或推送传递。

拉取传递

完全由你控制何时接收事件。例如，应用程序可能不会一直运行、不够稳定，或者你要在特定的时间处理数据。
完全由你控制事件的使用。例如，使用者应用程序中的下游服务或层出现问题，导致无法处理事件。在这种情况下，拉取传递 API 允许使用者应用将已读取的事件释放回代理，以便可以稍后传递。
你希望在接收事件时使用专用链接，这只能通过拉取传递实现，推送传递则不支持。
你无法公开终结点和使用推送传递，但可以连接到事件网格以使用事件。

推送传递

你希望避免通过不断的轮询来确定是否发生了系统状态更改。你希望在发生状态更改时使用事件网格向你发送事件。
你的某个应用程序无法发出出站调用。例如，你的组织可能担心数据外泄。但是，应用程序可以通过公共终结点接收事件。

后续步骤

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

Azure 事件网格命名空间概念

事件

另一种事件

CloudEvents

CloudEvents 内容模式

CloudEvents 支持

结构化内容模式

批量内容模式

批处理

二进制内容模式

何时使用 CloudEvents 的二进制或结构化内容模式

发布服务器

事件源

命名空间

吞吐量单位

主题

命名空间主题

事件订阅

拉取传递

使用拉取传递接收事件时的数据形状

推送传递

事件中心事件传递

推送和拉取传递

何时使用推送传递与拉取传递

拉取传递

推送传递

后续步骤

其他资源