將自訂欄位對應到事件格線結構描述

發行項
06/01/2023

如果您的事件資料不符合預期的事件方格結構描述，您仍然可以使用事件方格來將事件路由傳送給訂閱者。本文說明如何將結構描述對應到事件格線結構描述。

原始的事件結構描述

讓我們假設您的應用程式會以下列格式傳送事件：

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

儘管該格式不符合必要的結構描述，但事件格線可讓您將欄位對應到結構描述。或者，您可以在原始結構描述中接收值。

使用對應的欄位建立自訂主題

建立自訂主題時，指定如何將欄位從您的原始事件對應到事件格線結構描述。您可用來自訂對應的值有三個：

輸入結構描述值會指定結構描述的類型。可用的選項為 CloudEvents 結構描述、自訂事件結構描述或事件方格結構描述。預設值為事件方格結構描述。在您的結構描述與事件方格結構描述之間建立自訂對應時，請使用自訂事件結構描述。當事件為 CloudEvents 格式時，請使用 CloudEvents 結構描述。
對應預設值屬性會針對事件方格結構描述中的欄位指定預設值。您可以設定 subject、eventtype 和 dataversion 的預設值。一般而言，當您的自訂結構描述不包含對應到那三個欄位其中一個的欄位時，您會使用此參數。例如，您可以指定一律將該資料版本設定為 1.0。
對應欄位值會將欄位從您的結構描述對應到事件方格結構描述。您會以空格分隔的索引鍵/值組來指定值。針對索引鍵名稱，使用事件格線欄位的名稱。針對值，使用欄位的名稱。您可以針對 id、topic、eventtime、subject、eventtype 和 dataversion 使用索引鍵名稱。

若要使用 Azure CLI 建立自訂主題，請使用：

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

對於 PowerShell，請使用：

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

訂閱自訂主題時，需指定您想要用來接收事件的結構描述。您可指定 CloudEvents 結構描述、自訂事件結構描述或事件方格結構描述。預設值為事件方格結構描述。

下列範例會訂閱事件方格主題，並使用事件方格結構描述。對於 Azure CLI，請使用：

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>

下一個範例會使用事件的輸入結構描述：

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

下列範例會訂閱事件方格主題，並使用事件方格結構描述。對於 PowerShell，請使用：

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

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

下一個範例會使用事件的輸入結構描述：

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

將事件發行到主題

您現在已經準備好將事件傳送到自訂主題，並查看對應的結果。下列指令碼會在範例結構描述中公佈事件：

對於 Azure CLI，請使用：

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，請使用：

$endpoint = (Get-AzEventGridTopic -ResourceGroupName myResourceGroup -Name demotopic).Endpoint
$keys = Get-AzEventGridTopicKey -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 端點。這兩個訂用帳戶在不同的結構描述中傳遞了事件。

第一個訂用帳戶使用了事件格線結構描述。已傳遞事件的格式如下：

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

這些欄位包含自訂主題的對應。 myEventTypeField 會對應到 EventType。使用了 DataVersion 和 Subject 的預設值。 Data 物件包含原始的事件結構描述欄位。

第二個訂用帳戶使用了輸入事件結構描述。已傳遞事件的格式如下：

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

請注意已傳遞原始欄位。

下一步

如需事件傳遞和重試的相關資訊，請參閱事件格線訊息傳遞與重試。
如需 Event Grid 的簡介，請參閱關於 Event Grid。
若要快速地開始使用 Event Grid，請參閱使用 Azure Event Grid 建立和路由傳送自訂事件。

將自訂欄位對應到事件格線結構描述

原始的事件結構描述

使用對應的欄位建立自訂主題

訂閱事件格線主題

將事件發行到主題

下一步

其他資源