共用方式為

Azure 事件方格命名空間 - 支援 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 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 值的事件資料。 若要如此操作，請執行以下步驟：

  1. 包含具有資料編碼媒體類型的 datacontenttype 屬性。
  2. 如果媒體類型是以文字格式編碼，例如 text/plain、text/csv 或 application/xml，您應該使用 data 屬性搭配 JSON 字串，其中包含您要透過值傳達的內容。
  3. 如果媒體類型代表二進位編碼，您應該使用 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 標頭不能一併顯示。

重要

如果您打算在使用二進位內容模式時包含自己的屬性 (即延伸屬性)，請確定其名稱包含 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 的簡單方法，則可以使用結構化內容模式。 由於結構化內容模式中的 CloudEvent 會連同其中繼資料一起包含訊息，因此用戶端可以輕鬆地將其整體取用，並將其轉送至其他系統。

如果您知道下游應用程式只需要訊息，而不需任何額外的資訊 (也就是內容屬性)，就可以使用二進位內容模式。 在使用結構化內容模式時，您仍然可以從 CloudEvent 中取得事件資料 (訊息)，但如果取用者應用程式只在 HTTP 承載中具備資料，會更為容易。 例如，其他應用程式可以使用其他通訊協定，並且可以只對核心訊息感興趣，而不包含其中繼資料。 事實上，中繼資料可能只與立即的第一個躍點相關。 在此情況下，除了中繼資料之外，也具備您想要交換的資料，可以更輕鬆地處理和轉送。

相關內容