使用访问密钥将事件发布到 Azure 事件网格自定义主题

事件网格自定义主题是应用程序发送事件的端点，这样事件网格可以将这些事件路由给感兴趣的订阅者。本文将向您展示如何使用访问密钥将事件发布到自定义主题，这些密钥无需设置 Microsoft Entra ID 即可认证您的请求。你会获得主题端点和访问密钥，格式化事件负载，发送示例事件，并查看响应。

服务水平协议（SLA）仅适用于符合预期格式的帖子。

先决条件

一个 Azure 事件网格自定义主题。要创建一个，请参见“通过使用 Azure 门户向网络端点发送自定义事件。
Azure CLI、Azure PowerShell，或者访问 Azure 门户以获取主题端点和访问密钥。
一个可以发送HTTP POST请求的工具，比如 curl。

注意

Microsoft Entra 认证比访问密钥或共享访问签名（SAS）令牌认证提供了更好的认证支持。通过使用 Microsoft Entra 认证，Microsoft Entra 身份提供者会验证身份，因此你无需处理代码中的密钥。您还可以享受 Microsoft 标识平台内置的安全功能，如条件访问，这些功能有助于提升应用的安全性。有关详细信息，请参阅使用 Azure Microsoft Entra ID 对发布客户端进行身份验证。

获取主题终结点

要将事件发布到自定义主题，请使用以下 URI 格式发送 HTTP POST 请求： https://<topic-endpoint>?api-version=2018-01-01。例如，有效的 URI 为：https://exampletopic.chinanorth2-1.eventgrid.azure.cn/api/events?api-version=2018-01-01。要获取自定义主题的端点，可以使用Azure门户、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门户、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"
}]

发送示例事件

本部分介绍如何将示例事件发送到自定义主题。

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>"
    }]
  }
}

监视事件网格消息传递：了解如何跟踪和排查事件传送问题。
事件网格安全性和身份验证：了解如何使用身份验证密钥保护事件。
事件网格订阅架构：有关创建事件网格订阅的分步指南。

Last updated on 2026-09-11

使用访问密钥将事件发布到 Azure 事件网格 自定义主题