Förstå händelsefiltrering för Event Grid-prenumerationer

Artikel
11/15/2023

I den här artikeln beskrivs olika sätt att filtrera vilka händelser som skickas till slutpunkten. När du skapar en händelseprenumeration har du tre alternativ för filtrering:

Händelsetyper
Ämnet börjar med eller slutar med
Avancerade fält och operatorer

Azure Resource Manager-mall

Exemplen som visas i den här artikeln är JSON-kodfragment för att definiera filter i ARM-mallar (Azure Resource Manager). Ett exempel på en fullständig ARM-mall och distribution av en ARM-mall finns i Snabbstart: Dirigera Blob Storage-händelser till webbslutpunkt med hjälp av en ARM-mall. Här är några fler avsnitt i filter avsnittet i exemplet i snabbstarten. ARM-mallen definierar följande resurser.

Azure-lagringskonto
Systemämne för lagringskontot
Händelseprenumeration för systemämnet. Du ser underavsnittet filter i avsnittet händelseprenumeration.

I följande exempel filtrerar händelseprenumerationen för Microsoft.Storage.BlobCreated och Microsoft.Storage.BlobDeleted händelser.

{
  "resources": [
    {
      "type": "Microsoft.Storage/storageAccounts",
      "apiVersion": "2021-08-01",
      "name": "[parameters('storageAccountName')]",
      "location": "[parameters('location')]",
      "sku": {
        "name": "Standard_LRS"
      },
      "kind": "StorageV2",
      "properties": {
        "accessTier": "Hot"
      }
    },
    {
      "type": "Microsoft.EventGrid/systemTopics",
      "apiVersion": "2021-12-01",
      "name": "[parameters('systemTopicName')]",
      "location": "[parameters('location')]",
      "properties": {
        "source": "[resourceId('Microsoft.Storage/storageAccounts', parameters('storageAccountName'))]",
        "topicType": "Microsoft.Storage.StorageAccounts"
      },
      "dependsOn": [
        "[resourceId('Microsoft.Storage/storageAccounts', parameters('storageAccountName'))]"
      ]
    },
    {
      "type": "Microsoft.EventGrid/systemTopics/eventSubscriptions",
      "apiVersion": "2021-12-01",
      "name": "[format('{0}/{1}', parameters('systemTopicName'), parameters('eventSubName'))]",
      "properties": {
        "destination": {
          "properties": {
            "endpointUrl": "[parameters('endpoint')]"
          },
          "endpointType": "WebHook"
        },
        "filter": {
          "includedEventTypes": [
            "Microsoft.Storage.BlobCreated",
            "Microsoft.Storage.BlobDeleted"
          ]
        }
      },
      "dependsOn": [
        "[resourceId('Microsoft.EventGrid/systemTopics', parameters('systemTopicName'))]"
      ]
    }
  ]
}

Filtrering av händelsetyp

Som standard skickas alla händelsetyper för händelsekällan till slutpunkten. Du kan välja att endast skicka vissa händelsetyper till slutpunkten. Du kan till exempel få meddelanden om uppdateringar av dina resurser, men inte meddelas om andra åtgärder som borttagningar. I så fall filtrerar du efter Microsoft.Resources.ResourceWriteSuccess händelsetyp. Ange en matris med händelsetyperna eller ange All för att hämta alla händelsetyper för händelsekällan.

JSON-syntaxen för filtrering efter händelsetyp är:

"filter": {
  "includedEventTypes": [
    "Microsoft.Resources.ResourceWriteFailure",
    "Microsoft.Resources.ResourceWriteSuccess"
  ]
}

Ämnesfiltrering

För enkel filtrering efter ämne anger du ett start- eller slutvärde för ämnet. Du kan till exempel ange att ämnet slutar med .txt för att endast hämta händelser relaterade till att ladda upp en textfil till lagringskontot. Eller så kan du filtrera ämnet börjar med /blobServices/default/containers/testcontainer för att hämta alla händelser för containern men inte andra containrar i lagringskontot.

När du publicerar händelser i anpassade ämnen skapar du ämnen för dina händelser som gör det enkelt för prenumeranter att veta om de är intresserade av händelsen. Prenumeranter använder ämnesegenskapen för att filtrera och dirigera händelser. Överväg att lägga till sökvägen för var händelsen inträffade, så att prenumeranter kan filtrera efter segment i den sökvägen. Sökvägen gör det möjligt för prenumeranter att filtrera händelser smalt eller brett. Om du anger en sökväg för tre segment som /A/B/C i ämnet kan prenumeranter filtrera efter det första segmentet /A för att få en bred uppsättning händelser. Dessa prenumeranter får händelser med ämnen som /A/B/C eller /A/D/E. Andra prenumeranter kan filtrera efter /A/B för att få en smalare uppsättning händelser.

Exempel (Blob Storage-händelser)

Blobhändelser kan filtreras efter händelsetyp, containernamn eller namn på objektet som skapades eller togs bort.

Ämnet för Blob Storage-händelser använder formatet:

/blobServices/default/containers/<containername>/blobs/<blobname>

Om du vill matcha alla händelser för ett lagringskonto kan du lämna ämnesfiltren tomma.

Om du vill matcha händelser från blobar som skapats i en uppsättning containrar som delar ett prefix använder du ett subjectBeginsWith filter som:

/blobServices/default/containers/containerprefix

Om du vill matcha händelser från blobar som skapats i en specifik container använder du ett subjectBeginsWith filter som:

/blobServices/default/containers/containername/

Om du vill matcha händelser från blobar som skapats i en specifik container som delar ett blobnamnprefix använder du ett subjectBeginsWith filter som:

/blobServices/default/containers/containername/blobs/blobprefix

Om du vill matcha händelser från blobar som skapas i en specifik undermapp för en container använder du ett subjectBeginsWith filter som:

/blobServices/default/containers/{containername}/blobs/{subfolder}/

Om du vill matcha händelser från blobar som skapats i en specifik container som delar ett blobsuffix använder du ett subjectEndsWith filter som ".log" eller ".jpg".

Avancerad filtrering

Om du vill filtrera efter värden i datafälten och ange jämförelseoperatorn använder du alternativet för avancerad filtrering. I avancerad filtrering anger du följande:

operatortyp – typ av jämförelse.
key – fältet i de händelsedata som du använder för filtrering. Det kan vara ett tal, booleskt värde, en sträng eller en matris.
values – Värdet eller värdena som ska jämföras med nyckeln.

Key

Nyckeln är fältet i de händelsedata som du använder för filtrering. Det kan vara en av följande typer:

Antal
Booleskt
String

Array. Du måste ange enableAdvancedFilteringOnArrays egenskapen till true för att använda den här funktionen.

"filter":
{
    "subjectBeginsWith": "/blobServices/default/containers/mycontainer/blobs/log",
    "subjectEndsWith": ".jpg",
    "enableAdvancedFilteringOnArrays": true
}

För händelser i Cloud Events-schemat använder du följande värden för nyckeln: eventid, source, eventtype, eventtypeversioneller händelsedata (till exempel data.key1).

Om du använder Basic-nivån för Event Grid för händelser i Event Grid-schemat använder du följande värden för nyckeln: ID, Topic, Subject, EventType, DataVersioneller händelsedata (till exempel data.key1). För anpassat indataschema använder du fälten för händelsedata (till exempel data.key1). Om du vill komma åt fält i dataavsnittet använder du notationen . (punkt). Till exempel data.siteName, data.appEventTypeDetail.action för att komma åt siteName eller action för följande exempelhändelse.

	"data": {
		"appEventTypeDetail": {
			"action": "Started"
		},
		"siteName": "<site-name>",
		"clientRequestId": "None",
		"correlationRequestId": "None",
		"requestId": "292f499d-04ee-4066-994d-c2df57b99198",
		"address": "None",
		"verb": "None"
	},

Kommentar

Event Grid stöder inte filtrering på en matris med objekt. Det tillåter endast Sträng, Boolesk, Tal och Matris av samma typer (till exempel heltalsmatris eller strängmatris).

Värden

Värdena kan vara: tal, sträng, booleskt värde eller matris

Operatorer

Tillgängliga operatorer för tal är:

NumberIn

NumberIn-operatorn utvärderas till true om nyckelvärdet är ett av de angivna filtervärdena . I följande exempel kontrollerar den om värdet för counter attributet i data avsnittet är 5 eller 1.

"advancedFilters": [{
    "operatorType": "NumberIn",
    "key": "data.counter",
    "values": [
        5,
        1
    ]
}]

Om nyckeln är en matris kontrolleras alla värden i matrisen mot matrisen med filtervärden. Här är pseudokoden med nyckeln: [v1, v2, v3] och filtret: [a, b, c]. Alla nyckelvärden med datatyper som inte matchar filtrets datatyp ignoreras.

FOR_EACH filter IN (a, b, c)
    FOR_EACH key IN (v1, v2, v3)
        IF filter == key
            MATCH

NumberNotIn

NumberNotIn utvärderas till true om nyckelvärdet inte är något av de angivna filtervärdena. I följande exempel kontrollerar den om värdet för counter attributet i data avsnittet inte är 41 och 0.

"advancedFilters": [{
    "operatorType": "NumberNotIn",
    "key": "data.counter",
    "values": [
        41,
        0
    ]
}]

FOR_EACH filter IN (a, b, c)
    FOR_EACH key IN (v1, v2, v3)
        IF filter == key
            FAIL_MATCH

NumberLessThan

Operatorn NumberLessThan utvärderas till true om nyckelvärdet är mindre än det angivna filtervärdet . I följande exempel kontrollerar den om värdet för counter attributet i data avsnittet är mindre än 100.

"advancedFilters": [{
    "operatorType": "NumberLessThan",
    "key": "data.counter",
    "value": 100
}]

Om nyckeln är en matris kontrolleras alla värden i matrisen mot filtervärdet. Här är pseudokoden med nyckeln: [v1, v2, v3]. Alla nyckelvärden med datatyper som inte matchar filtrets datatyp ignoreras.

FOR_EACH key IN (v1, v2, v3)
    IF key < filter
        MATCH

NumberGreaterThan

Operatorn NumberGreaterThan utvärderas till true om nyckelvärdet är större än det angivna filtervärdet . I följande exempel kontrollerar den om värdet för counter attributet i data avsnittet är större än 20.

"advancedFilters": [{
    "operatorType": "NumberGreaterThan",
    "key": "data.counter",
    "value": 20
}]

FOR_EACH key IN (v1, v2, v3)
    IF key > filter
        MATCH

NumberLessThanOrEquals

Operatorn NumberLessThanOrEquals utvärderas till true om nyckelvärdet är mindre än eller lika med det angivna filtervärdet . I följande exempel kontrollerar den om värdet för counter attributet i data avsnittet är mindre än eller lika med 100.

"advancedFilters": [{
    "operatorType": "NumberLessThanOrEquals",
    "key": "data.counter",
    "value": 100
}]

FOR_EACH key IN (v1, v2, v3)
    IF key <= filter
        MATCH

NumberGreaterThanOrEquals

Operatorn NumberGreaterThanOrEquals utvärderas till true om nyckelvärdet är större än eller lika med det angivna filtervärdet . I följande exempel kontrollerar den om värdet för counter attributet i data avsnittet är större än eller lika med 30.

"advancedFilters": [{
    "operatorType": "NumberGreaterThanOrEquals",
    "key": "data.counter",
    "value": 30
}]

FOR_EACH key IN (v1, v2, v3)
    IF key >= filter
        MATCH

NumberInRange

NumberInRange-operatorn utvärderas till true om nyckelvärdet finns i något av de angivna filterintervallen. I följande exempel kontrollerar den om värdet key1 för attributet i data avsnittet finns i något av de två intervallen: 3,14159 – 999,95, 3000 – 4 000.

{
    "operatorType": "NumberInRange",
    "key": "data.key1",
    "values": [[3.14159, 999.95], [3000, 4000]]
}

Egenskapen values är en matris med intervall. I föregående exempel är det en matris med två intervall. Här är ett exempel på en matris med ett intervall att kontrollera.

Matris med ett intervall:

{
    "operatorType": "NumberInRange",
    "key": "data.key1",
    "values": [[3000, 4000]]
}

Om nyckeln är en matris kontrolleras alla värden i matrisen mot matrisen med filtervärden. Här är pseudokoden med nyckeln: [v1, v2, v3] och filtret: en matris med intervall. I den här pseudokoden a är och b låga och höga värden för varje intervall i matrisen. Alla nyckelvärden med datatyper som inte matchar filtrets datatyp ignoreras.

FOR_EACH (a,b) IN filter.Values
    FOR_EACH key IN (v1, v2, v3)
       IF key >= a AND key <= b
           MATCH

NumberNotInRange

Operatorn NumberNotInRange utvärderas till true om nyckelvärdet inte finns i något av de angivna filterintervallen. I följande exempel kontrollerar den om värdet key1 för attributet i data avsnittet finns i något av de två intervallen: 3,14159 – 999,95, 3000 – 4 000. Om den är det returnerar operatorn false.

{
    "operatorType": "NumberNotInRange",
    "key": "data.key1",
    "values": [[3.14159, 999.95], [3000, 4000]]
}

Egenskapen values är en matris med intervall. I föregående exempel är det en matris med två intervall. Här är ett exempel på en matris med ett intervall att kontrollera.

Matris med ett intervall:

{
    "operatorType": "NumberNotInRange",
    "key": "data.key1",
    "values": [[3000, 4000]]
}

FOR_EACH (a,b) IN filter.Values
    FOR_EACH key IN (v1, v2, v3)
        IF key >= a AND key <= b
            FAIL_MATCH

Den tillgängliga operatorn för booleska värden är:

BoolEquals

Operatorn BoolEquals utvärderas till true om nyckelvärdet är det angivna booleska värdefiltret. I följande exempel kontrollerar den om värdet för isEnabled attributet i data avsnittet är true.

"advancedFilters": [{
    "operatorType": "BoolEquals",
    "key": "data.isEnabled",
    "value": true
}]

Om nyckeln är en matris kontrolleras alla värden i matrisen mot filtrets booleska värde. Här är pseudokoden med nyckeln: [v1, v2, v3]. Alla nyckelvärden med datatyper som inte matchar filtrets datatyp ignoreras.

FOR_EACH key IN (v1, v2, v3)
    IF filter == key
        MATCH

Tillgängliga operatorer för strängar är:

StringContains

StringContains utvärderas till true om nyckelvärdet innehåller något av de angivna filtervärdena (som delsträngar). I följande exempel kontrollerar den om värdet för key1 attributet i data avsnittet innehåller någon av de angivna understrängarna: microsoft eller azure. Till exempel azure data factory har azure i den.

"advancedFilters": [{
    "operatorType": "StringContains",
    "key": "data.key1",
    "values": [
        "microsoft", 
        "azure"
    ]
}]