发布到 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 Az PowerShell 模块。This article has been updated to use the Azure Az PowerShell module. 若要与 Azure 交互,建议使用的 PowerShell 模块是 Az PowerShell 模块。The Az PowerShell module is the recommended PowerShell module for interacting with Azure. 若要开始使用 Az PowerShell 模块,请参阅安装 Azure PowerShellTo get started with the Az PowerShell module, see Install Azure PowerShell. 若要了解如何迁移到 Az PowerShell 模块,请参阅 将 Azure PowerShell 从 AzureRM 迁移到 AzTo learn how to migrate to the Az PowerShell module, see Migrate Azure PowerShell from AzureRM to Az.

端点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. 一个事件允许的最大大小也为 1 MB。The maximum allowed size for an event is also 1 MB. 超过 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