将自定义字段映射到事件网格架构Map custom fields to Event Grid schema

即使事件数据与预期的事件网格架构不匹配,也仍然可以使用事件网格将事件路由到订阅服务器。If your event data doesn't match the expected Event Grid schema, you can still use Event Grid to route event to subscribers. 本文介绍如何将你的架构映射到事件网格架构。This article describes how to map your schema to the Event Grid schema.

重要

使用 PowerShell 的 Azure 功能必须已安装 AzureRM 模块。Using this Azure feature from PowerShell requires the AzureRM module installed. 该模块是旧模块,仅适用于 Windows PowerShell 5.1,它不再接收新功能。This is an older module only available for Windows PowerShell 5.1 that no longer receives new features. 针对相同版本的 PowerShell 进行安装时,AzAzureRM 模块不兼容。The Az and AzureRM modules are not compatible when installed for the same versions of PowerShell. 如果需要两个版本,请执行以下操作:If you need both versions:

  1. 在 PowerShell 5.1 会话中卸载 Az 模块Uninstall the Az module from a PowerShell 5.1 session.
  2. 在 PowerShell 5.1 会话中安装 AzureRM 模块Install the AzureRM module from a PowerShell 5.1 session.
  3. 下载并安装 PowerShell Core 6.x 或更高版本Download and install PowerShell Core 6.x or later.
  4. 在 PowerShell Core 会话中安装 Az 模块Install the Az module in a PowerShell Core session.

安装预览功能Install preview feature

此功能为预览版。This feature is in preview. 若要使用它,必须安装预览扩展或模块。To use it, you must install a preview extension or module.

安装适用于 Azure CLI 的扩展Install extension for Azure CLI

对于 Azure CLI,需要事件网格扩展For Azure CLI, you need the Event Grid extension.

对于本地安装:For a local installation:

  1. 在本地卸载 Azure CLI。Uninstall Azure CLI locally.
  2. 安装最新版本的 Azure CLI。Install the latest version of Azure CLI.
  3. 启动命令窗口。Launch command window.
  4. 卸载早期版本的扩展 az extension remove -n eventgridUninstall previous versions of the extension az extension remove -n eventgrid
  5. 安装扩展 az extension add -n eventgridInstall the extension az extension add -n eventgrid

安装适用于 PowerShell 的模块Install module for PowerShell

对于 PowerShell,需要 AzureRM.EventGrid 模块For PowerShell, you need the AzureRM.EventGrid module.

对于本地安装:For a local installation:

  1. 以管理员身份打开 PowerShell 控制台Open PowerShell console as administrator
  2. 安装模块 Install-Module -Name AzureRM.EventGrid -AllowPrerelease -Force -Repository PSGalleryInstall the module Install-Module -Name AzureRM.EventGrid -AllowPrerelease -Force -Repository PSGallery

如果 -AllowPrerelease 参数不可用,请使用以下步骤:If the -AllowPrerelease parameter isn't available, use the following steps:

  1. 运行 Install-Module PowerShellGet -ForceRun Install-Module PowerShellGet -Force
  2. 运行 Update-Module PowerShellGetRun Update-Module PowerShellGet
  3. 关闭 PowerShell 控制台Close the PowerShell console
  4. 以管理员身份重启 PowerShellRestart PowerShell as administrator
  5. 安装模块 Install-Module -Name AzureRM.EventGrid -AllowPrerelease -Force -Repository PSGalleryInstall the module Install-Module -Name AzureRM.EventGrid -AllowPrerelease -Force -Repository PSGallery

原始事件架构Original event schema

假设你有一个以下述格式发送事件的应用程序:Let's suppose you have an application that sends events in the following format:

[
  {
    "myEventTypeField":"Created",
    "resource":"Users/example/Messages/1000",
    "resourceData":{"someDataField1":"SomeDataFieldValue"}
  }
]

虽然该格式与所需的架构不符,但你仍可使用事件网格将字段映射到架构。Although that format doesn't match the required schema, Event Grid enables you to map your fields to the schema. 也可以原始架构接收值。Or, you can receive the values in the original schema.

使用映射的字段创建自定义主题Create custom topic with mapped fields

在创建自定义主题时,请指定如何将字段从原始事件映射到事件网格架构。When creating a custom topic, specify how to map fields from your original event to the event grid schema. 可以使用三个值来自定义映射:There are three values you use to customize the mapping:

  • 输入架构值指定架构的类型。The input schema value specifies the type of schema. 可用选项包括 CloudEvents 架构、自定义事件架构或事件网格架构。The available options are CloudEvents schema, custom event schema, or Event Grid schema. 默认值为事件网格架构。The default value is Event Grid schema. 在你的架构和事件网格架构之间创建自定义映射时,请使用自定义事件架构。When creating custom mapping between your schema and the event grid schema, use custom event schema. 当事件采用 CloudEvents 架构时,请使用 Cloudevents 架构。When events are in the CloudEvents schema, use Cloudevents schema.

  • “映射默认值”属性指定事件网格架构中字段的默认值。The mapping default values property specifies default values for fields in the Event Grid schema. 可以为 subjecteventtypedataversion 设置默认值。You can set default values for subject, eventtype, and dataversion. 通常情况下,如果自定义架构不包括这三个字段中的一个的对应字段,请使用此参数。Typically, you use this parameter when your custom schema doesn't include a field that corresponds to one of those three fields. 例如,可以指定将数据版本始终设置为 1.0For example, you can specify that data version is always set to 1.0.

  • “映射字段”值将字段从你的架构映射到事件网格架构。The mapping fields value maps fields from your schema to the event grid schema. 请以空格分隔的键/值对形式指定值。You specify values in space-separated key/value pairs. 对于键名称,请使用事件网格字段的名称。For the key name, use the name of the event grid field. 对于值,请使用字段的名称。For the value, use the name of your field. 可以对 idtopiceventtimesubjecteventtypedataversion 使用键名称。You can use key names for id, topic, eventtime, subject, eventtype, and dataversion.

要使用 Azure CLI 创建自定义主题,请使用:To create a custom topic with Azure CLI, use:

# If you have not already installed the extension, do it now.
# This extension is required for preview features.
az extension add --name eventgrid

az eventgrid topic create \
  -n demotopic \
  -l chinaeast2 \
  -g myResourceGroup \
  --input-schema customeventschema \
  --input-mapping-fields eventType=myEventTypeField \
  --input-mapping-default-values subject=DefaultSubject dataVersion=1.0

对于 PowerShell,请使用:For PowerShell, use:

# If you have not already installed the module, do it now.
# This module is required for preview features.
Install-Module -Name AzureRM.EventGrid -AllowPrerelease -Force -Repository PSGallery

New-AzureRmEventGridTopic `
  -ResourceGroupName myResourceGroup `
  -Name demotopic `
  -Location chinaeast2 `
  -InputSchema CustomEventSchema `
  -InputMappingField @{eventType="myEventTypeField"} `
  -InputMappingDefaultValue @{subject="DefaultSubject"; dataVersion="1.0" }

订阅事件网格主题Subscribe to event grid topic

订阅自定义主题时,请指定要用于接收事件的架构。When subscribing to the custom topic, you specify the schema you would like to use for receiving the events. 可以指定 CloudEvents 架构、自定义事件架构或事件网格架构。You specify the CloudEvents schema, custom event schema, or Event Grid schema. 默认值为事件网格架构。The default value is Event Grid schema.

以下示例订阅一个事件网格主题并使用事件网格架构。The following example subscribes to an event grid topic and uses the Event Grid schema. 对于 Azure CLI,请使用:For Azure CLI, use:

topicid=$(az eventgrid topic show --name demoTopic -g myResourceGroup --query id --output tsv)

az eventgrid event-subscription create \
  --source-resource-id $topicid \
  --name eventsub1 \
  --event-delivery-schema eventgridschema \
  --endpoint <endpoint_URL>

下一示例使用事件的输入架构:The next example uses the input schema of the event:

az eventgrid event-subscription create \
  --source-resource-id $topicid \
  --name eventsub2 \
  --event-delivery-schema custominputschema \
  --endpoint <endpoint_URL>

以下示例订阅一个事件网格主题并使用事件网格架构。The following example subscribes to an event grid topic and uses the Event Grid schema. 对于 PowerShell,请使用:For PowerShell, use:

$topicid = (Get-AzureRmEventGridTopic -ResourceGroupName myResourceGroup -Name demoTopic).Id

New-AzureRmEventGridSubscription `
  -ResourceId $topicid `
  -EventSubscriptionName eventsub1 `
  -EndpointType webhook `
  -Endpoint <endpoint-url> `
  -DeliverySchema EventGridSchema

下一示例使用事件的输入架构:The next example uses the input schema of the event:

New-AzureRmEventGridSubscription `
  -ResourceId $topicid `
  -EventSubscriptionName eventsub2 `
  -EndpointType webhook `
  -Endpoint <endpoint-url> `
  -DeliverySchema CustomInputSchema

将事件发布到主题Publish event to topic

现在可以将事件发送到自定义主题并查看映射结果了。You're now ready to send an event to the custom topic, and see the result of the mapping. 以下脚本采用示例架构发布事件:The following script to post an event in the example schema:

对于 Azure CLI,请使用:For Azure CLI, use:

endpoint=$(az eventgrid topic show --name demotopic -g myResourceGroup --query "endpoint" --output tsv)
key=$(az eventgrid topic key list --name demotopic -g myResourceGroup --query "key1" --output tsv)

event='[ { "myEventTypeField":"Created", "resource":"Users/example/Messages/1000", "resourceData":{"someDataField1":"SomeDataFieldValue"} } ]'

curl -X POST -H "aeg-sas-key: $key" -d "$event" $endpoint

对于 PowerShell,请使用:For PowerShell, use:

$endpoint = (Get-AzureRmEventGridTopic -ResourceGroupName myResourceGroup -Name demotopic).Endpoint
$keys = Get-AzureRmEventGridTopicKey -ResourceGroupName myResourceGroup -Name demotopic

$htbody = @{
    myEventTypeField="Created"
    resource="Users/example/Messages/1000"
    resourceData= @{
        someDataField1="SomeDataFieldValue"
    }
}

$body = "["+(ConvertTo-Json $htbody)+"]"
Invoke-WebRequest -Uri $endpoint -Method POST -Body $body -Headers @{"aeg-sas-key" = $keys.Key1}

现在,请查看 WebHook 终结点。Now, look at your WebHook endpoint. 这两个订阅以不同架构分发了事件。The two subscriptions delivered events in different schemas.

第一个订阅使用了事件网格架构。The first subscription used event grid schema. 已分发事件的格式为:The format of the delivered event is:

{
  "id": "aa5b8e2a-1235-4032-be8f-5223395b9eae",
  "eventTime": "2018-11-07T23:59:14.7997564Z",
  "eventType": "Created",
  "dataVersion": "1.0",
  "metadataVersion": "1",
  "topic": "/subscriptions/<subscription-id>/resourceGroups/myResourceGroup/providers/Microsoft.EventGrid/topics/demotopic",
  "subject": "DefaultSubject",
  "data": {
    "myEventTypeField": "Created",
    "resource": "Users/example/Messages/1000",
    "resourceData": {
      "someDataField1": "SomeDataFieldValue"
    }
  }
}

这些字段包含来自自定义主题的映射。These fields contain the mappings from the custom topic. myEventTypeField 映射到 EventTypemyEventTypeField is mapped to EventType. 使用 DataVersion 和“主题”的默认值。The default values for DataVersion and Subject are used. “数据”对象包含原始的事件架构字段。The Data object contains the original event schema fields.

第二个订阅使用了输入事件架构。The second subscription used the input event schema. 已分发事件的格式为:The format of the delivered event is:

{
  "myEventTypeField": "Created",
  "resource": "Users/example/Messages/1000",
  "resourceData": {
    "someDataField1": "SomeDataFieldValue"
  }
}

请注意,分发的是原始字段。Notice that the original fields were delivered.

后续步骤Next steps