发布到 Azure 事件网格的自定义主题Post to custom topic for Azure Event Grid

本文说明如何将事件发布到自定义主题。This article describes how to post an event to a custom topic. 它显示发布和事件数据的格式。It shows the format of the post and event data. 服务级别协议 (SLA) 仅适用于与预期格式匹配的发布。The Service Level Agreement (SLA) only applies to posts that match the expected format.

备注

本文进行了更新,以便使用新的 Azure PowerShell Az 模块。This article has been updated to use the new Azure PowerShell Az module. 你仍然可以使用 AzureRM 模块,至少在 2020 年 12 月之前,它将继续接收 bug 修补程序。You can still use the AzureRM module, which will continue to receive bug fixes until at least December 2020. 若要详细了解新的 Az 模块和 AzureRM 兼容性,请参阅新 Azure Powershell Az 模块简介To learn more about the new Az module and AzureRM compatibility, see Introducing the new Azure PowerShell Az module. 有关 Az 模块安装说明,请参阅安装 Azure PowerShellFor Az module installation instructions, see Install Azure PowerShell.

端点Endpoint

使用 URI 格式 https://<topic-endpoint>?api-version=2018-01-01 将 HTTP POST 发送到自定义主题。When sending the HTTP POST to a custom topic, use the URI format: https://<topic-endpoint>?api-version=2018-01-01.

例如,有效的 URI 为:https://exampletopic.chinanorth2-1.eventgrid.azure.cn/api/events?api-version=2018-01-01For example, a valid URI is: https://exampletopic.chinanorth2-1.eventgrid.azure.cn/api/events?api-version=2018-01-01.

若要使用 Azure CLI 获取自定义主题的终结点,请使用:To get the endpoint for a custom topic with Azure CLI, use:

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

若要使用 Azure PowerShell 获取自定义主题的终结点,请使用:To get the endpoint for a custom topic with Azure PowerShell, use:

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

在请求中包含一个名为 aeg-sas-key 的标头值,其中包含身份验证密钥。In the request, include a header value named aeg-sas-key that contains a key for authentication.

例如,有效的标头值为 aeg-sas-key: VXbGWce53249Mt8wuotr0GPmyJ/nDT4hgdEj9DpBeRr38arnnm5OFg==For example, a valid header value is aeg-sas-key: VXbGWce53249Mt8wuotr0GPmyJ/nDT4hgdEj9DpBeRr38arnnm5OFg==.

若要使用 Azure CLI 获取自定义主题的密钥,请使用:To get the key for a custom topic with Azure CLI, use:

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

若要使用 PowerShell 获取自定义主题的密钥,请使用:To get the key for a custom topic with PowerShell, use:

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

事件数据Event data

就自定义主题而言,顶级数据包含与标准资源所定义事件相同的字段。For custom topics, the top-level data contains the same fields as standard resource-defined events. 这些属性之一是包含自定义主题所特有的属性的数据属性。One of those properties is a data property that contains properties unique to the custom topic. 作为事件发布者,你确定该数据对象的属性。As event publisher, you determine the properties for that data object. 使用以下架构:Use the following schema:

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

有关这些属性的说明,请参阅 Azure 事件网格事件架构For a description of these properties, see Azure Event Grid event schema. 将事件发布到事件网格主题时,数组的总大小最大可为 1 MB。When posting events to an event grid topic, the array can have a total size of up to 1 MB. 数组中的每个事件都限制为 64 KB(正式版)或 1 MB(预览版)。Each event in the array is limited to 64 KB (General Availability) or 1 MB (preview).

备注

正式版服务级别协议 (GA) 涵盖了大小高达 64 KB 的事件。An event of size up to 64 KB is covered by General Availability (GA) Service Level Agreement (SLA). 预览版中目前支持最大为 1 MB 的事件。The support for an event of size up to 1 MB is currently in preview. 超过 64 KB 的事件以 64 KB 为增量计费。Events over 64 KB are charged in 64-KB increments.

例如,有效的事件数据架构是:For example, a valid event data schema is:

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

响应Response

发布到主题终结点后,你将收到响应。After posting to the topic endpoint, you receive a response. 响应是标准 HTTP 响应代码。The response is a standard HTTP response code. 一些常见的响应如下所示:Some common responses are:

结果Result 响应Response
SuccessSuccess 200 正常200 OK
事件数据的格式不正确Event data has incorrect format 400 错误请求400 Bad Request
访问密钥无效Invalid access key 401 未授权401 Unauthorized
终结点不正确Incorrect endpoint 404 未找到404 Not Found
数组或事件超出大小限制Array or event exceeds size limits 413 有效负载太大413 Payload Too Large

对于错误,消息正文采用以下格式:For errors, the message body has the following format:

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

后续步骤Next steps