Azure 事件方格事件結構描述

發行項
09/26/2024

本文說明事件方格架構，這是專屬、不可延伸且功能完整的事件格式。事件方格仍然支援此事件格式，並將繼續支援它。不過， CloudEvents 是建議使用的事件格式。如果您使用使用事件方格格式的應用程式，您可能會在 [CloudEvents] 區段中找到有用的資訊，其中描述 Event Grid 與 Event Grid 支援的 CloudEvents 格式之間的轉換。

本文詳細說明事件方格格式的屬性和架構。事件包含一組四個必要必要屬性。這些是任何發行者所有事件的常見屬性。資料物件具有每個發行者的特定屬性。針對系統主題，這些是資源提供者 (例如 Azure 儲存體或 Azure 事件中樞) 的特定屬性。

事件來源會將事件傳送至陣列中的 Azure 事件方格，其中可包含數個事件物件。將事件張貼至事件方格主題時，陣列可包含最多 1 MB 的大小總計。陣列中的每個事件會限制為 1 MB。如果事件或陣列大於大小限制，您會收到回應 413承載太大。但作業會以 64 KB 遞增計費。因此，超過 64 KB 的事件會產生作業費用，如同它們是多個事件。例如，130 KB 的事件會產生作業，就像是三個不同的事件一樣。

事件方格會在包含單一事件的陣列中將事件傳送至訂閱者。此行為未來可能會變更。

您可以在事件結構描述存放區中找到事件方格事件的 JSON 結構描述，以及每個 Azure 發行者的資料承載。

注意

事件方格事件架構的支援不會淘汰，但我們不會在未來對它進行任何重大改善。我們建議您使用 CloudEvents 架構，此架構提供事件結構和元數據描述的標準化和通訊協定無關的定義。如需詳細資訊，請參閱具有 Azure 事件方格的 CloudEvents v1.0 架構。

結構描述

下列範例顯示所有事件發行者會使用的屬性：

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

例如，針對 Azure Blob 記憶體事件發佈的架構為：

[
  {
    "topic": "/subscriptions/{subscription-id}/resourceGroups/Storage/providers/Microsoft.Storage/storageAccounts/xstoretestaccount",
    "subject": "/blobServices/default/containers/oc2d2817345i200097container/blobs/oc2d2817345i20002296blob",
    "eventType": "Microsoft.Storage.BlobCreated",
    "eventTime": "2017-06-26T18:41:00.9584103Z",
    "id": "831e1650-001e-001b-66ab-eeb76e069631",
    "data": {
      "api": "PutBlockList",
      "clientRequestId": "6d79dbfb-0e37-4fc4-981f-442c9ca65760",
      "requestId": "831e1650-001e-001b-66ab-eeb76e000000",
      "eTag": "0x8D4BCC2E4835CD0",
      "contentType": "application/octet-stream",
      "contentLength": 524288,
      "blobType": "BlockBlob",
      "url": "https://oc2d2817345i60006.blob.core.windows.net/oc2d2817345i200097container/oc2d2817345i20002296blob",
      "sequencer": "00000000000004420000000000028963",
      "storageDiagnostics": {
        "batchId": "b68529f3-68cd-4744-baa4-3c0498ec19f0"
      }
    },
    "dataVersion": "",
    "metadataVersion": "1"
  }
]

事件屬性

所有事件都包含相同的下列最上層資料：

屬性	型別	必要	描述
`topic`	字串	否，但如果包含，則必須完全符合事件方格主題 Azure Resource Manager 標識符。如果未包含，事件方格戳記會套用至事件。	事件來源的完整資源路徑。此欄位無法寫入。事件方格提供此值。
`subject`	字串	Yes	發行者定義事件主旨的路徑。
`eventType`	字串	Yes	此事件來源已註冊的事件類型之一。
eventTime	string	Yes	事件產生的時間，以提供者的 UTC 時間為準。
`id`	字串	Yes	事件的唯一識別碼。
`data`	object	Yes	資源提供者特有的事件資料。
`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 服務使用 Event Grid 格式，下表提供來協助您了解當使用 CloudEvents 和 Event Grid 格式做為主題中的輸入架構以及事件訂用帳戶中的輸出架構時所支援的轉換。使用 CloudEvents 做為輸入結構描述時，無法使用事件方格輸出結構描述，因為 CloudEvents 支援事件方格結構描述不支援的延伸模組屬性。

輸入結構描述	輸出結構描述
CloudEvents 格式	CloudEvents 格式
事件方格格式	CloudEvents 格式
事件方格格式	事件方格格式

下一步

如需 Azure Event Grid 的簡介，請參閱什麼是 Event Grid？
若要了解 Event Grid 訂用帳戶的建立，請參閱 Event Grid 訂用帳戶結構描述。

共用方式為

Azure 事件方格事件結構描述

結構描述

事件屬性

CloudEvents

下一步

意見反應

其他資源