使用 access keys 將事件發佈到 Azure 事件方格自訂主題

Event Grid 自訂主題是應用程式傳送事件的端點，讓 Event Grid 能將這些事件路由給有興趣的訂閱者。本文將教你如何利用存取金鑰將事件發佈到自訂主題，這些金鑰在不需設定 Microsoft Entra ID 的情況下驗證你的請求。你會取得主題端點和存取鍵，格式化事件有效載荷，傳送範例事件，然後審查回應。

服務水準協議（SLA）僅適用於符合預期格式的貼文。

先決條件

Azure 事件方格自訂主題。要建立一個，請參考「透過 Azure 入口傳送自訂事件到網頁端點」。
使用 Azure CLI、Azure PowerShell 或存取 Azure 入口網站，以取得主題端點和存取金鑰。
一個能發送 HTTP POST 請求的工具，例如 curl。

注意

Microsoft Entra 認證提供比存取金鑰或共享存取簽章（SAS）令牌認證更好的認證支援。透過使用 Microsoft Entra 認證，Microsoft Entra 身份提供者會驗證身份，因此你不必處理程式碼中的金鑰。你也能受益於 Microsoft 身分識別平台內建的安全功能，例如條件存取（Conditional Access），有助於提升應用程式的安全性。如需詳細資訊，請參閱使用 Microsoft Entra ID 驗證發佈用戶端。

取得主題端點

若要將事件發佈到自訂主題，請使用以下 URI 格式發送 HTTP POST 請求： https://<topic-endpoint>?api-version=2018-01-01 例如，https://exampletopic.westus2-1.eventgrid.azure.net/api/events?api-version=2018-01-01 便是有效的 URI。要取得自訂主題的端點，請使用 Azure portal、Azure CLI 或 Azure PowerShell。

在 Azure 入口網站事件網格主題頁面的概覽標籤中找到該主題的端點。

az eventgrid topic show --name <topic-name> -g <topic-resource-group> --query "endpoint"

(Get-AzEventGridTopic -ResourceGroupName <topic-resource-group> -Name <topic-name>).Endpoint

取得存取金鑰

在要求中，包含名為 aeg-sas-key 的標頭值，其中包含用於驗證的金鑰。例如，有效的標頭值為 aeg-sas-key: xxxxxxxxxxxxxxxxxxxxxxx。要取得自訂主題的鍵，可以使用 Azure portal、Azure CLI 或 Azure PowerShell。

要取得自訂主題的存取金鑰，請在 Azure 入口網站的事件網格主題頁面選擇存取鍵標籤。

az eventgrid topic key list --name <topic-name> -g <topic-resource-group> --query "key1"

(Get-AzEventGridTopicKey -ResourceGroupName <topic-resource-group> -Name <topic-name>).Key1

格式化事件酬載

將每個事件格式化為 JSON 物件。頂層欄位與標準的資源定義事件相同，屬性 data 包含你自訂主題獨有的屬性。作為發佈者，你定義了物件的內容 data 。關於每個屬性的說明，請參見 Azure 事件方格事件結構。

[
  {
    "id": string,
    "eventType": string,
    "subject": string,
    "eventTime": string-in-date-time-format,
    "data":{
      object-unique-to-each-publisher
    },
    "dataVersion": string
  }
]

在建造有效載荷時，請考慮以下尺寸限制：

事件陣列的總大小可達 1 MB。
單一事件的最大容量為 1 MB。超過 64 KB 的事件會以 64 KB 為單位收費。
一個批次最多可包含 5,000 個事件。

以下範例顯示有效的事件承載資料：

[{
  "id": "1807",
  "eventType": "recordInserted",
  "subject": "myapp/vehicles/motorcycles",
  "eventTime": "2017-08-10T21:03:07+00:00",
  "data": {
    "make": "Ducati",
    "model": "Monster"
  },
  "dataVersion": "1.0"
}]

傳送一個範例事件

本節說明如何將範例事件傳送至自訂主題。

在 Azure 入口網站中啟動 Cloud Shell。
在 Cloud Shell 中，在 Bash 或 PowerShell 工作階段中，從 Azure PowerShell 或 Azure CLI 執行此命令。

endpoint=$(az eventgrid topic show --name <topic name> -g <resource group name> --query "endpoint" --output tsv)

key=$(az eventgrid topic key list --name <topic name> -g <resource group name> --query "key1" --output tsv)

event='[ {"id": "'"$RANDOM"'", "eventType": "recordInserted", "subject": "myapp/vehicles/motorcycles", "eventTime": "'`date +%Y-%m-%dT%H:%M:%S%z`'", "data":{ "make": "Ducati", "model": "Monster"},"dataVersion": "1.0"} ]'

curl -X POST -H "aeg-sas-key: $key" -d "$event" $endpoint

$resourceGroupName = "<resource group name>"
$topicName = "<topic name>"

$endpoint = (Get-AzEventGridTopic -ResourceGroupName $resourceGroupName -Name $topicName).Endpoint

$keys = Get-AzEventGridTopicKey -ResourceGroupName $resourceGroupName -Name $topicName

$eventID = Get-Random 99999
#Date format should be SortableDateTimePattern (ISO 8601)
$eventDate = Get-Date -Format s

#Construct body using Hashtable
$htbody = @{
    id= $eventID
    eventType="recordInserted"
    subject="myapp/vehicles/motorcycles"
    eventTime= $eventDate
    data= @{
        make="Ducati"
        model="Monster"
    }
    dataVersion="1.0"
}

#Use ConvertTo-Json to convert event body from Hashtable to JSON Object
#Append square brackets to the converted JSON payload since they are expected in the event's JSON payload syntax
$body = "["+(ConvertTo-Json $htbody)+"]"

Invoke-WebRequest -Uri $endpoint -Method POST -Body $body -Headers @{"aeg-sas-key" = $keys.Key1}

檢視回應

在你發佈到主題端點後，你會收到回覆。回應是標準的 HTTP 回應碼。一些常見回應有：

結果	回應
成功	200 確定
事件資料的格式不正確	400 錯誤請求
存取金鑰無效	401 未經授權
端點不正確	404 找不到
陣列或事件超過大小限制	413 酬載過大

對於錯誤，訊息主體採用以下格式：

{
    "error": {
        "code": "<HTTP status code>",
        "message": "<description>",
        "details": [{
            "code": "<HTTP status code>",
            "message": "<description>"
    }]
  }
}

監控事件網格訊息傳遞：學習如何追蹤與排解事件傳遞問題。
Event Grid 的安全與認證：了解如何用認證金鑰保護你的活動。
Event Grid 訂閱架構：建立 Event Grid 訂閱的逐步指引。

意見反應

此頁面對您有幫助嗎？

上次更新時間： 2026-08-28