Azure 事件方格命名空間概念

發行項
05/22/2024

本文將介紹與命名空間主題相關聯的主要概念和功能。

事件

事件是完整說明系統中發生內容的最小量資訊。我們通常會將事件稱為離散事件，因為代表了系統的離散、獨立事實，提供可行的深入解析。每個事件都有一般資訊，例如：事件的 source、事件發生的 time，以及唯一識別碼。每個事件也有 type，這通常是描述事件用途公告類型的唯一標識碼。

例如，在 Azure 儲存體中建立新檔案的相關事件含有該檔案相關詳細資料，例如 lastTimeModified 值。「事件中樞」事件含有已擷取檔案的 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）訊息代理程式功能搭配使用。

雲端事件

事件方格命名空間主題接受符合雲端原生運算基金會 (CNCF) 開放式標準 CloudEvents 1.0 規格的事件，意即使用 JSON 格式的 HTTP 通訊協定繫結。 CloudEvent 是一種訊息，其中包含所傳達的內容、稱為事件數據，以及其相關元數據。事件導向結構中的事件資料通常會帶有宣告系統狀態變更的資訊。 CloudEvents 中繼資料是由一組屬性所組成，這些屬性會提供訊息的內容相關資訊，例如來源位置 (來源系統)、其類型等等。符合 CloudEvents 規格的所有有效訊息都必須包含下列必要內容屬性：

CloudEvents 規格也會定義您在使用事件方格時可包含的 [選用] 和 [延伸內容屬性]。

使用事件方格時，CloudEvents 是慣用的事件格式，因為其有記載良好的使用案例 (傳輸事件的模式、事件格式等)、擴充性，以及經過改善的互通性。 CloudEvents 藉由提供用以發佈和取用事件的常見事件格式，改善互通性。允許路由傳送和處理事件的統一工具和標準方式。

CloudEvents 內容模式

CloudEvents 規格會定義三種內容模式：二進位、結構化和批次。

重要

使用任何 con 帳篷模式您可以交換文字（JSON、text/*等等）或二進位編碼的事件數據。二進位內容模式並非專門用來傳送二進位資料。

內容模式並不是指您使用的編碼、二進位或文字，而是指事件資料和其中繼資料的描述和交換方式。結構化內容模式會使用單一結構 (例如 JSON 物件)，其中內容屬性和事件資料都在 HTTP 承載中。二進位內容模式會分隔內容屬性，這些屬性會對應至 HTTP 標頭，以及事件資料 (根據 Content-Type 中設定的媒體類型所編碼的 HTTP 承載)。

CloudEvents 支援

下表顯示目前支援的 CloudEvents 規格：

CloudEvents 內容模式	是否支援？
結構化 JSON	Yes
結構化批次 JSON	是的，用於發行事件
二進位	是的，用於發行事件

允許的事件大小上限是 1 MB。超過 64 KB 的事件會以 64 KB 遞增計費。

結構化內容模式

CloudEvents 結構化內容模式中的訊息在 HTTP 承載中，同時具有內容屬性和事件資料。

重要

事件方格目前支援將 CloudEvents JSON 格式搭配 HTTP。

以下是使用 JSON 格式的結構化模式 CloudEvents 範例。中繼資料 (非「data」的所有屬性) 和訊息/事件資料 (「data」物件) 都會使用 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 屬性，其值為 JSON 字串，包含 BASE64 編碼的二進位值。

例如，此 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 標頭不能一併顯示。

重要

如果您打算在使用二進位 con 帳篷模式時包含自己的屬性（即擴充屬性），請確定其名稱是由 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 的二進位或結構化內容模式

如果您想要跨躍點和通訊協議轉送 CloudEvents 的簡單方法，則可以使用結構化內容模式。由於結構化 con 中的 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 個字元。可以包含英數字元和連字號 (-)，但不能包含空格。
此名稱在每個區域中必須是唯一的。

輸送量單位

輸送量單位 (TU) 會定義命名空間中輸入和輸出的事件速率容量。如需詳細資訊，請參閱 Azure 事件方格配額和限制。

主題

主題會保存已發佈至事件方格的事件。您通常會針對相關事件的集合使用主題資源。我們通常會將命名空間內的主題稱為命名空間主題。

命名空間主題

命名空間主題是在事件方格命名空間內建立的主題。您的應用程式會將事件發佈至 HTTP 命名空間端點，以指定透過邏輯方式包含已發布事件的命名空間主題。在設計應用程式時，您必須決定要建立多少個主題。對於相對大型的解決方案，請為每個類別的相關事件建立命名空間主題。例如，請考慮管理使用者帳戶的應用程式，以及關於客戶訂單的另一個應用程式。不太可能所有事件訂閱者都想要來自這兩個應用程式的事件。若要區分疑慮，請建立兩個命名空間主題：每個應用程式各一個主題。讓事件消費者根據其需求訂閱主題。針對小型解決方案，您可能會偏好將所有事件傳送至單一主題。

命名空間主題支援提取傳遞和推送傳遞。請參閱使用提取或推送傳遞的時機，以協助您決定推送傳遞是否為符合您需求的正確方法。

事件訂閱

事件訂用帳戶是與單一主題相關聯的設定資源。除此之外，您可以使用事件訂用帳戶來設定事件選取準則，以定義主題中可用事件總數集的訂閱者適用事件集合。您可以根據訂閱者的需求來篩選事件。例如，您可以依事件類型篩選事件。如果使用 JSON 物件做為資料屬性的值，您也可以定義事件資料屬性的篩選準則。如需資源屬性的詳細資訊，請在事件方格 REST API 中尋找控制平面作業。

如需建立命名空間主題訂用帳戶的範例，請參閱使用 CLI 使用命名空間主題發佈和取用訊息。

注意

相較於用於自訂、網域、合作夥伴和系統主題 (事件網格基本) 的事件訂用帳戶，命名空間主題下的事件訂用帳戶具有簡化的資源模型。如需詳細資訊，請參閱建立、檢視和管理事件訂閱。

提取傳遞

您的應用程式可透過提取傳遞連接至事件方格，以使用佇列型語意讀取訊息。當應用程式連接到事件方格以取用事件時，會控管事件耗用量率及其時間。取用者應用程式也可以在連接到事件方格時使用私人端點，以使用私人 IP 空間讀取事件。

提取傳遞支援下列作業，以讀取訊息和控管訊息狀態：接收、認可、發行、拒絕，以及更新鎖定。如需詳細資訊，請參閱提取傳遞概觀。

使用提取傳遞接收事件時的資料圖形

當使用提取傳遞來傳遞事件時，事件網格會包含物件陣列，其中包括 event 和 brokerProperties 物件。 event 屬性的值是以結構化內容模式傳遞的 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 事件中樞作為目的地。未來，事件方格命名空間將支援更多目的地，包括 Event Grid Basic 支援的所有目的地。

事件中樞事件遞送

事件方格會使用事件中樞 SDK，使用 AMQP 將事件傳送至事件中樞。事件會以位元組陣列的形式傳送，陣列中的每個元素都包含 CloudEvent。

推送和提取遞送

事件方格支援使用 HTTP 的推送和提取事件傳遞。您可以透過推送傳遞，在事件訂閱、Webhook 或 Azure 服務中定義目的地，而事件方格會將事件傳送至該目的地。透過提取傳遞，訂閱者應用程式會連接到事件方格以取用事件。事件方格命名空間中的主題支援提取傳遞。

重要

事件中樞支援作為命名空間主題訂閱的目的地。在即將推出的版本中，事件方格命名空間將支援事件方格基本中目前適用的所有目的地，以及其他目的地。

使用推送傳遞與提取傳遞的時機

以下是一般指導方針，可協助您決定何時使用提取或推送傳遞。

提取傳遞

您需要完整控管接收事件的時機。例如，您的應用程式可能不會一直處於運作狀態、不夠穩定，或者您在特定時間處理資料。
您需要完全控管事件取用。例如，取用者應用程式中的下游服務或層級發生問題，導致您無法處理事件。在此情況下，提取傳遞 API 可讓取用者應用程式將已讀取的事件釋回訊息代理程式，以便稍後傳遞。
您想要在接收事件時使用私人連結，這只能透共提取傳遞使用，而無法透過推送傳遞使用。
您無法公開端點並使用推送傳遞，但您可以連線至事件方格來取用事件。

推送傳遞

您想要避免持續輪詢，以判斷系統狀態變更是否已發生。您選擇在事件狀態變更時，使用事件方格將事件傳送給您。
您有無法進行輸出呼叫的應用程式。例如，您的組織可能會擔心資料外流。不過，您的應用程式可以透過公用端點接收事件。

下一步

如需 Event Grid 的簡介，請參閱關於 Event Grid。
若要開始使用命名空間主題，請參閱使用命名空間主題發佈事件。

共用方式為

Azure 事件方格命名空間概念

事件

另一種事件

雲端事件

CloudEvents 內容模式

CloudEvents 支援

結構化內容模式

批次內容模式

批次處理

二進位內容模式

何時使用 CloudEvents 的二進位或結構化內容模式

發行者

事件來源

命名空間

輸送量單位

主題

命名空間主題

事件訂閱

提取傳遞

使用提取傳遞接收事件時的資料圖形

推送傳遞

事件中樞事件遞送

推送和提取遞送

使用推送傳遞與提取傳遞的時機

提取傳遞

推送傳遞

下一步

意見反應

意見反應

其他資源