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

本文提供有关如何使用访问密钥将事件发布到 Azure 事件网格自定义主题的指导。 你将了解所需的终结点格式、身份验证标头、事件架构以及如何发送示例事件。

服务级别协议 (SLA) 仅适用于与预期格式匹配的发布。

注意

Microsoft Entra 身份验证提供的身份验证支持优于访问密钥或共享访问签名 (SAS) 令牌身份验证所提供的身份验证支持。 使用 Microsoft Entra 身份验证时,将针对 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 门户中“事件网格主题”页面的“概述”选项卡中找到主题的终结点

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