Azure 事件方格命名空間概念

發行項
01/11/2024

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

事件

事件是最少量的資訊，可完整描述系統中發生的情況。我們通常會將事件稱為離散事件，因為它代表系統的不同自我獨立事實，可提供可採取動作的深入解析。每個事件都有一般資訊，例如：事件的 source、事件發生的 time，以及唯一識別碼。每個事件也都有 type，這通常是描述事件用途公告類型的唯一標識符。

例如，在 Azure 儲存體中建立新檔案的相關事件含有該檔案相關詳細資料，例如 lastTimeModified 值。事件中樞事件具有所擷取檔案的URL。 Orders 微服務中新訂單的相關事件，可能會有 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）訊息代理程式功能搭配使用。

雲端事件

事件方格命名空間主題會接受符合 Cloud Native Computing Foundation （CNCF）開放式標準 CloudEvents 1.0 規格的事件，並使用具有 JSON 格式的 HTTP 通訊協定系結。 CloudEvent 是一種訊息，其中包含所傳達的內容、稱為事件數據，以及其相關元數據。事件驅動架構中的事件數據通常會帶有宣告系統狀態變更的資訊。 CloudEvents 元數據是由一組屬性所組成，這些屬性會提供訊息的內容相關信息，例如來源系統、其類型等等。符合 CloudEvents 規格的所有有效訊息都必須包含下列必要內容屬性：

CloudEvents 規格也會定義選擇性和擴充內容屬性，您可以在使用事件方格時包含這些屬性。

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

CloudEvents con 帳篷模式 s

CloudEvents 規格會定義三個 con 帳篷模式：binary、structured 和 batched。

重要

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

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

CloudEvents 支援

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

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

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

結構化 con 帳篷模式

CloudEvents 結構化 con 帳篷模式中的訊息在 HTTP 承載中同時具有內容屬性和事件數據。

重要

事件方格目前支援使用 HTTP 的 CloudEvents JSON 格式。

以下是使用 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/csv或 application/xml等text/plain文字格式編碼，您應該使用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 屬性的詳細資訊，請參閱處理數據。

如需此 con 帳篷模式的詳細資訊，請參閱 CloudEvents HTTP 結構化 con 帳篷模式規格。

Batched con 帳篷模式

事件方格目前支援將 CloudEvents 發佈至事件方格時，JSON 批處理的 con 帳篷模式。此 con 帳篷模式會使用 JSON 陣列，以結構化 con 帳篷模式填滿 CloudEvents。例如，您的應用程式可以使用如下的陣列來發佈兩個事件。同樣地，如果您使用事件方格的數據平面 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。

二進位 con 帳篷模式

二進位 con 中的 CloudEvent 帳篷模式其內容屬性描述為 HTTP 標頭。 HTTP 標頭的名稱是前面加上 ce-的內容屬性名稱。標頭 Content-Type 會反映事件數據編碼所在的媒體類型。

重要

使用二進位 con 時帳篷模式 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 的二進位或結構化 con 帳篷模式

如果您想要跨躍點和通訊協議轉送 CloudEvents 的簡單方法，您可以使用結構化 con 帳篷模式。由於結構化 con 中的 CloudEvent 帳篷模式包含訊息及其元數據，因此用戶端很容易取用整個訊息，並將其轉送至其他系統。

如果您使用二進位 con 帳篷模式如果您知道下游應用程式只需要訊息，而不需要任何額外的資訊（也就是內容屬性）。雖然使用結構化 con 帳篷模式您仍然可以從 CloudEvent 中取得事件數據（訊息），但如果取用者應用程式只是在 HTTP 承載中擁有它，就比較容易。例如，其他應用程式可以使用其他通訊協定，而且可能只對核心訊息感興趣，而不是其元數據。事實上，元數據可能只與立即的第一個躍點相關。在此情況下，除了您想要交換的數據，除了其元數據之外，也可讓您更輕鬆地處理和轉送。

發行者

發行者是指將事件傳送至事件方格的應用程式。它可以是事件來源、事件來源所在的相同應用程式。使用命名空間主題時，您可以從自己的應用程式發佈事件。

事件來源

事件來源是事件發生的位置。每個事件來源都支援一或多個事件類型。例如，您的應用程式是系統所定義之自定義事件的事件來源。使用命名空間主題時，支援的事件來源是您自己的應用程式。

命名空間

事件方格命名空間是下列資源的管理容器：

資源	支援的通訊協定
命名空間主題	HTTP
主題空間	MQTT
用戶端	MQTT
用戶端群組	MQTT
CA 憑證	MQTT
權限繫結	MQTT

使用 Azure 事件方格命名空間，您可以將相關資源分組，並將其管理為 Azure 訂用帳戶中的單一單位。它為您提供唯一的完整功能變數名稱（FQDN）。

命名空間會公開兩個端點：

使用命名空間主題支援一般傳訊需求的 HTTP 端點。
適用於使用 MQTT 之 IoT 傳訊或解決方案的 MQTT 端點。

命名空間也提供 DNS 整合的網路端點。它也提供一系列訪問控制和網路整合管理功能，例如公用IP輸入篩選和私人連結。它也是命名空間中所含資源的受控識別容器。

以下是關於命名空間的幾個點：

命名空間是具有 tags 和 location 屬性的追蹤資源，一旦建立，就可以在上 resources.azure.com找到。
命名空間的名稱長度可以是 3-50 個字元。它可以包含英數位元和連字元（-），而且沒有空格。
每個區域的名稱必須是唯一的。
目前支持的區域： 美國中部、東亞、美國東部、美國東部 2、北歐、美國中南部、東南亞、阿聯酋北部、西歐、美國西部 2、美國西部 3。

輸送量單位

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

主題

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

命名空間主題

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

命名空間主題支援提取傳遞和推送傳遞。查看何時使用提取或推送傳遞，以協助您判斷提取傳遞是否為符合您需求的正確方法。

事件訂閱

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

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

注意

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

提取傳遞

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

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

使用提取傳遞接收事件時的數據圖形

使用提取傳遞傳遞傳遞事件時，Event Grid 會包含對象的陣列，而該數位會包含事件和 brokerProperties 物件。事件屬性的值是在結構化 con 帳篷模式中傳遞的 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 服務中定義目的地，而事件方格會將事件傳送至該目的地。透過 提取傳遞，訂閱者應用程式會連線到事件方格以取用事件。事件方格命名空間中的主題支援提取傳遞。

重要

事件中樞支持作為命名空間主題訂用帳戶的目的地。在即將推出的版本中，Event Grid 命名空間將支援事件方格 Basic 中目前提供的所有目的地，以及其他目的地。

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

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

提取傳遞

您需要完整控制接收事件的時機。例如，您的應用程式可能一直未啟動、不夠穩定，或在特定時間處理數據。
您需要完全控制事件耗用量。例如，取用者應用程式中的下游服務或層發生問題，導致您無法處理事件。在此情況下，提取傳遞 API 可讓取用者應用程式將已讀取的事件釋回訊息代理程式，以便稍後傳遞。
您想要在接收事件時使用私人連結，這隻能與提取傳遞搭配使用，而不是推送傳遞。
您無法公開端點並使用推送傳遞，但您可以連線到事件方格來取用事件。

推送傳遞

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

下一步

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

Azure 事件方格 命名空間概念

事件

另一種事件

雲端事件

CloudEvents con 帳篷模式 s

CloudEvents 支援

結構化 con 帳篷模式

Batched con 帳篷模式

批次處理

二進位 con 帳篷模式

何時使用 CloudEvents 的二進位或結構化 con 帳篷模式

發行者

事件來源

命名空間

輸送量單位

主題

命名空間主題

事件訂閱

提取傳遞

使用提取傳遞接收事件時的數據圖形

推送傳遞

事件中樞事件傳遞

推送和提取傳遞

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

提取傳遞

推送傳遞

下一步

其他資源

Azure 事件方格命名空間概念