HTTP 提取傳遞

本文以什麼是 Azure 事件方格？和事件方格概念文章為基礎，在您開始使用事件方格的 HTTP 提取傳遞之前提供基本資訊。 其中涵蓋基本概念、資源模型和支援的訊息傳遞模式。 在本文結尾，您將找到實用文章連結，引導您了解如何使用事件方格並提供深入概念資訊。

雲端事件

事件方格命名空間主題接受符合雲端原生運算基金會 (CNCF) 開放式標準 CloudEvents 1.0 規格的事件，意即使用 JSON 格式的 HTTP 通訊協定繫結。

如需詳細資訊，請參閱 CloudEvents 支援。

CloudEvents 內容模式

CloudEvents 規格定義三種您可使用的內容模式：二進位、結構化和批次。

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

如需詳細資訊，請參閱 CloudEvents 內容模式。

訊息和事件

CloudEvent 通常會傳遞事件資料以宣告系統中發生的事件，意即系統狀態變更。 不過，您可使用 CloudEvents 以傳達任何類型的資料。 例如，您可能想要使用 CloudEvents 交換模式，以要求動作的命令訊息傳送至下游應用程式。 另一個範例是當您將訊息從事件方格的 MQTT 代理路由至主題時。 在此案例中，您將路由包裝在 CloudEvents 信封的 MQTT 訊息。

提取傳遞

您的應用程式可透過提取傳遞連線至事件方格，以使用佇列型語意讀取 CloudEvents 訊息。

提取傳遞提供下列事件取用優點：

• 按您自身步調、規模或應用程式支援的輸入速率取用事件。

• 按所選時間取用事件。 例如，根據業務需求，訊息會在夜間處理。

• 透過私人連結使用事件，讓您的資料使用私人 IP 空間。

佇列事件訂閱

接收事件或使用管理事件狀態的作業時，應用程式會指定命名空間 HTTP 端點、主題名稱和佇列事件訂閱名稱。 佇列事件訂閱的 deliveryMode 設定為 "queue"。 使用佇列事件訂閱以透過提取傳遞 API 取用事件。 如需如何建立這些資源的詳細資訊，請參閱建立命名空間、主題和事件訂閱。

您可使用事件訂閱以定義事件的篩選準則，以便可有效定義可透過該事件訂閱取用的事件集。 一或多個訂閱者 (取用者) 應用程式可連線至相同命名空間端點，並使用相同的主題和事件訂閱。

提取傳遞作業

使用提取傳遞時，應用程式會使用下列作業。

• 使用接收作業以透過事件方格的單一要求讀取一或多個事件。 依預設，訊息代理程等候最多 60 秒，讓事件可供使用。 例如，事件可在第一次發佈時供傳遞。 成功接收要求會傳回零或多個事件。 如果事件可供使用，則會盡可能傳回可用事件，最多至要求的事件計數。 事件方格也會傳回每個事件讀取的鎖定權杖。
• 鎖定權杖是一種控制代碼，可識別您可用來控制其狀態的事件。
• 取用者應用程式收到事件並處理後，便會認可該事件。 此作業會只是事件方格以刪除事件，使其不會傳新傳遞至另一個用戶端。 取用者應用程式透過在到期前指定鎖定權杖，以認可一或多個單一要求的權杖。

在某些其他情況下，取用者應用程式可能要釋放或拒絕事件。

• 取用者應用程式會將接收的事件釋放至單一事件方格，因為尚未準備處理該事件，並使其可供重新傳遞。 其方式是呼叫釋放作業，並使用鎖定權杖識別躍傳回至事件方格的事件。 應用程式可控制事件是否應立即釋放，或是否應在事件可供重新傳遞之前使用延遲。

• 如果有防止取用者應用程式處理事件的條件 (可能為永久性)，您可選擇拒絕事件。 例如，格式錯誤訊息可能因無法成功剖析而遭到拒絕。 如果有無效信件目的地，則拒絕的事件為無效信件。 否則會卸除這些事件。

執行提取傳遞作業的範圍

當您叫用接收、認可、釋放、拒絕或更新鎖定作業時，這些動作會在事件訂閱的內容中執行。 例如，如果您認可事件，該事件便無法透過呼叫認可動作時使用的事件訂閱使用。 其他事件訂閱仍然可使用「相同」事件。 這是因為事件訂閱取得已發佈事件的副本。 這些事件副本在事件訂閱中實際上不同。 每個事件都有自己的狀態，獨立於其他事件。

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

當使用提取傳遞來傳遞事件時，事件網格會包含物件陣列，其中包括 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
                }
            }
        }
    ]
}

推送和提取傳遞

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

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

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

提取傳遞

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

推送傳遞

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

下一步

下列文章提供您如何使用事件方格的資訊，也提供您概念的額外資訊。

• 使用命名空間主題發佈和訂閱事件。

其他實用連結

• 控制平面和資料平面 SDK。
• 資料平面 SDK 宣告，其中包含大量資訊、範本和連結。
• 配額和限制。