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

本文说明如何使用访问密钥发布自定义主题事件。 它显示发布和事件数据的格式。 服务级别协议 (SLA) 仅适用于与预期格式匹配的发布。

注意

Microsoft Entra 身份验证提供的身份验证支持优于访问密钥或共享访问签名 (SAS) 令牌身份验证所提供的身份验证支持。 使用 Microsoft Entra 身份验证时,将针对 Microsoft Entra 标识提供者来验证标识。 作为开发人员,如果使用 Microsoft Entra 身份验证,则不需要在代码中处理密钥。 你还将受益于 Microsoft 标识平台中内置的所有安全功能,例如条件访问,它们可帮助你提高应用程序的安全情况。 有关详细信息,请参阅使用 Azure Microsoft Entra ID 对发布客户端进行身份验证

端点

使用 URI 格式 https://<topic-endpoint>?api-version=2018-01-01 将 HTTP POST 发送到自定义主题。 例如,有效的 URI 为:https://exampletopic.chinanorth2-1.eventgrid.azure.cn/api/events?api-version=2018-01-01。 若要使用 Azure CLI 获取自定义主题的终结点,请使用:

可以在 Azure 门户中“事件网格主题”页面的“概述”选项卡中找到主题的终结点

显示 Azure 门户上“事件网格主题”页面的屏幕截图,其中突出显示了主题终结点。

在请求中包含一个名为 aeg-sas-key 的标头值,其中包含身份验证密钥。 例如,有效的标头值为 aeg-sas-key: xxxxxxxxxxxxxxxxxxxxxxx。 若要使用 Azure CLI 获取自定义主题的密钥,请使用:

若要获取自定义主题的访问密钥,请在 Azure 门户中的“事件网格主题”页面上选择“访问密钥”选项卡

显示 Azure 门户上“事件网格主题”页面的“访问密钥”选项卡的屏幕截图。

事件数据

就自定义主题而言,顶级数据包含与标准资源所定义事件相同的字段。 这些属性之一是包含自定义主题所特有的属性的 data 属性。 作为事件发布者,由你确定该数据对象的属性。 以下是架构:

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

有关这些属性的说明,请参阅 Azure 事件网格事件架构。 当客户端将事件发送到事件网格主题时,数组的总大小最大可为 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

响应

发布到主题终结点后,你将收到响应。 响应是标准 HTTP 响应代码。 一些常见的响应如下所示:

结果 响应
Success 200 正常
事件数据的格式不正确 400 错误请求
访问密钥无效 401 未授权
终结点不正确 404 未找到
数组或事件超出大小限制 413 有效负载太大

对于错误,消息正文采用以下格式:

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