使用访问密钥将事件发布到 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 获取自定义主题的终结点，请使用：

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

若要使用 Azure PowerShell 获取自定义主题的终结点，请使用：

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

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

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

若要使用 PowerShell 获取自定义主题的密钥，请使用：

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

事件数据

就自定义主题而言，顶级数据包含与标准资源所定义事件相同的字段。 这些属性之一是包含自定义主题所特有的属性的 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"
}]

响应

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

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

对于错误，消息正文采用以下格式：

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

后续步骤