共用方式為


發佈至 Azure 事件方格中的命名空間主題,以及取用其中的事件

本文提供使用 curl bash 殼層命令來發佈、接收和認可事件的提取傳遞簡介。 事件方格資源是使用 CLI 命令建立的。 本文適用於提取傳遞功能的快速測試。 如需使用資料平面 SDK 的範例程式碼,請參閱 .NET 或 Java 範例。 對於 Java,我們在以下兩篇文章中提供了範例程式碼:發佈事件接收事件快速入門。 如需提取傳遞模型的詳細資訊,請參閱概念提取傳遞概觀文章。

如果您沒有 Azure 訂閱,請在開始之前,先建立 Azure 免費帳戶

必要條件

  • 本文需要 2.0.70 版或更新版本的 Azure CLI。 如果您是使用 Azure Cloud Shell,就已安裝最新版本。

建立資源群組

使用 az group create 命令來建立 Azure 資源群組。 您可以使用此資源群組來包含本文中建立的所有資源。

使用 Cloud Shell 執行命令的一般步驟如下:

  • 選取 [開啟 Cloud Shell],以查看右窗格中的 [Azure Cloud Shell] 視窗。
  • 將命令複製並貼到 Azure Cloud Shell 視窗中。
  • 按 ENTER 鍵,執行此命令。
  1. 宣告變數以保存 Azure 資源群組的名稱。 將 <your-resource-group-name> 取代為您偏好的值,以指定資源群組的名稱。

    resource_group="<your-resource-group-name>"
    
  2. 建立資源群組。 視需要變更位置。

    az group create --name $resource_group --location eastus
    

啟用事件方格資源提供者

  1. 如果您先前在 Azure 訂用帳戶中從未使用過事件方格,可能必須註冊事件方格資源提供者。 執行下列命令以註冊提供者:

    az provider register --namespace Microsoft.EventGrid
    
  2. 可能需要一點時間才能完成註冊。 若要查看狀態,請執行下列命令:

    az provider show --namespace Microsoft.EventGrid --query "registrationState"
    

    registrationStateRegistered 時,代表已準備好繼續進行。

建立命名空間

事件方格命名空間會提供使用者定義的端點,作為您發佈事件的目的地。 下列範例使用 Azure Cloud Shell 中的 Bash,在您的資源群組中建立命名空間。 命名空間名稱必須是唯一的,因為這是網域名稱系統 (DNS) 項目的一部分。 命名空間名稱應符合下列規則:

  • 應介於 3-50 個字元之間。
  • 應是區域中唯一的。
  • 允許的字元只有 a-z、A-Z、0-9 和 -
  • 不應以 MicrosoftSystemEventGrid 等保留的關鍵字前置詞開頭。
  1. 宣告變數以保存事件方格命名空間的名稱。 將 <your-namespace-name> 取代為您偏好的值,以指定命名空間的名稱。

    namespace="<your-namespace-name>"
    
  2. 建立命名空間。 您可以變更其部署位置。

    az eventgrid namespace create -g $resource_group -n $namespace -l eastus
    

建立命名空間主題

建立主題,用以保存發佈至命名空間端點的所有事件。

  1. 宣告變數以保存命名空間主題的名稱。 將 <your-topic-name> 取代為您偏好的值,以指定命名空間的名稱主題。

    topic="<your-topic-name>"
    
  2. 建立命名空間主題:

    az eventgrid namespace topic create -g $resource_group -n $topic --namespace-name $namespace 
    

建立事件訂閱

建立一個事件訂用帳戶,將其傳遞模式設為支援提取傳遞佇列。 如需所有設定選項的詳細資訊,請參閱最新的事件方格控制平面 REST API

  1. 宣告變數,以保存命名空間主題的事件訂用帳戶名稱。 將 <your-event-subscription-name> 取代為您偏好的值,以指定事件訂用帳戶的名稱。

    event_subscription="<your-event-subscription-name>"
    
  2. 建立命名空間主題的事件訂用帳戶:

    az eventgrid namespace topic event-subscription create -g $resource_group --topic-name $topic -n $event_subscription --namespace-name $namespace --delivery-configuration "{deliveryMode:Queue,queue:{receiveLockDurationInSeconds:300,maxDeliveryCount:4,eventTimeToLive:P1D}}"
    

將事件傳送至您的主題

現在,依照本節中的步驟,將範例事件傳送至命名空間主題。

列出命名空間存取金鑰

  1. 取得與您建立的命名空間相關聯的存取金鑰。 您可以在發佈事件時使用其中之一進行驗證。 若要列出金鑰,必須先取得完整的命名空間資源識別碼。 請執行下列命令加以取得:

    namespace_resource_id=$(az eventgrid namespace show -g $resource_group -n $namespace --query "id" --output tsv)
    
  2. 從命名空間取得第一個金鑰:

    key=$(az eventgrid namespace list-key -g $resource_group --namespace-name $namespace --query "key1" --output tsv)
    

發佈事件

  1. 擷取命名空間主機名稱。 您可以用它來撰寫事件傳送到的命名空間 HTTP 端點。 下列作業在 API 版本 2023-06-01-preview 首次提供。

    publish_operation_uri="https://"$(az eventgrid namespace show -g $resource_group -n $namespace --query "topicsConfiguration.hostname" --output tsv)"/topics/"$topic:publish?api-version=2023-06-01-preview
    
  2. 建立符合範例 CloudEvents 規範的事件:

    event=' { "specversion": "1.0", "id": "'"$RANDOM"'", "type": "com.yourcompany.order.ordercreatedV2", "source" : "/mycontext", "subject": "orders/O-234595", "time": "'`date +%Y-%m-%dT%H:%M:%SZ`'", "datacontenttype" : "application/json", "data":{ "orderId": "O-234595", "url": "https://yourcompany.com/orders/o-234595"}} '
    

    data 元素是事件的承載。 任何語式正確的 JSON 都可以進入這個欄位。 如需可在事件中放入的屬性 (也稱為內容屬性) 的詳細資訊,請參閱 CloudEvents 規格。

  3. 使用 CURL 將事件傳送至主題。 CURL 是可傳送 HTTP 要求的公用程式。

    curl -X POST -H "Content-Type: application/cloudevents+json" -H "Authorization:SharedAccessKey $key" -d "$event" $publish_operation_uri
    

接收事件

請使用參照事件訂用帳戶的端點從事件方格接收事件。

  1. 執行下列命令以撰寫該端點:

    receive_operation_uri="https://"$(az eventgrid namespace show -g $resource_group -n $namespace --query "topicsConfiguration.hostname" --output tsv)"/topics/"$topic/eventsubscriptions/$event_subscription:receive?api-version=2023-06-01-preview
    
  2. 提交要求以取用事件:

    curl -X POST -H "Content-Type: application/json" -H "Authorization:SharedAccessKey $key" $receive_operation_uri
    

認可事件

收到事件之後,請將該事件傳遞至您的應用程式進行處理。 成功處理事件之後,該事件就不再需要位於事件訂用帳戶中。 若要指示事件方格刪除事件,您可以使用在接收作業的回應上取得的鎖定權杖來認可該事件。

  1. 在上一個步驟中,您應已收到回應,其中包含具有 lockToken 屬性的 brokerProperties 物件。 請複製鎖定權杖值,並將其設定在環境變數上:

    lockToken="<paste-the-lock-token-here>"
    
  2. 現在,建置認可作業承載,指定您要確認的事件的鎖定權杖。

    acknowledge_request_payload=' { "lockTokens": ["'$lockToken'"]} '
    
  3. 繼續使用認可作業 URI 建置字串:

    acknowledge_operation_uri="https://"$(az eventgrid namespace show -g $resource_group -n $namespace --query "topicsConfiguration.hostname" --output tsv)"/topics/"$topic/eventsubscriptions/$event_subscription:acknowledge?api-version=2023-06-01-preview
    
  4. 最後,提交要求以認可收到的事件:

    curl -X POST -H "Content-Type: application/json" -H "Authorization:SharedAccessKey $key" -d "$acknowledge_request_payload" $acknowledge_operation_uri
    

    如果在鎖定權杖到期 (我們建立事件訂用帳戶時設定為 300 秒) 之前執行認可作業,您應該會看到類似下列範例的回應:

    {"succeededLockTokens":["CiYKJDQ4NjY5MDEyLTk1OTAtNDdENS1BODdCLUYyMDczNTYxNjcyMxISChDZae43pMpE8J8ovYMSQBZS"],"failedLockTokens":[]}
    

下一步

若要深入了解提取傳遞模型,請參閱提取傳遞概觀