Omówienie filtrowania zdarzeń dla subskrypcji usługi Event Grid

Artykuł
12/12/2024

W tym artykule opisano różne sposoby filtrowania zdarzeń wysyłanych do punktu końcowego. Podczas tworzenia subskrypcji zdarzeń dostępne są trzy opcje filtrowania:

Typy zdarzeń
Temat zaczyna się od lub kończy się na
Zaawansowane pola i operatory

Szablon usługi Azure Resource Manager

Przykłady przedstawione w tym artykule to fragmenty kodu JSON służące do definiowania filtrów w szablonach usługi Azure Resource Manager (ARM). Aby zapoznać się z przykładem kompletnego szablonu usługi ARM i wdrażania szablonu usługi ARM, zobacz Szybki start: kierowanie zdarzeń usługi Blob Storage do internetowego punktu końcowego przy użyciu szablonu usługi ARM. Poniżej przedstawiono kilka sekcji dotyczących filter sekcji z przykładu w przewodniku Szybki start. Szablon usługi ARM definiuje następujące zasoby.

Konto magazynu Azure
Temat systemowy dla konta magazynu
Subskrypcja zdarzeń dla tematu systemowego. filter Zobacz podsekcję w sekcji subskrypcji zdarzeń.

W poniższym przykładzie subskrypcja zdarzeń filtruje wartości Microsoft.Storage.BlobCreated i Microsoft.Storage.BlobDeleted zdarzenia.

{
  "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'))]"
      ]
    }
  ]
}

Filtrowanie typów zdarzeń

Domyślnie wszystkie typy zdarzeń dla źródła zdarzeń są wysyłane do punktu końcowego. Możesz zdecydować się na wysyłanie tylko niektórych typów zdarzeń do punktu końcowego. Możesz na przykład otrzymywać powiadomienia o aktualizacjach zasobów, ale otrzymywać powiadomienia o innych operacjach, takich jak usunięcia. W takim przypadku filtruj Microsoft.Resources.ResourceWriteSuccess według typu zdarzenia. Podaj tablicę z typami zdarzeń lub określ All , aby pobrać wszystkie typy zdarzeń dla źródła zdarzeń.

Składnia JSON do filtrowania według typu zdarzenia to:

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

Filtrowanie tematu

W przypadku prostego filtrowania według tematu określ wartość początkową lub końcową tematu. Na przykład można określić, że temat kończy się na .txt , aby pobierać tylko zdarzenia związane z przekazywaniem pliku tekstowego na konto magazynu. Możesz też filtrować temat, zaczynając od /blobServices/default/containers/testcontainer , aby pobrać wszystkie zdarzenia dla tego kontenera, ale nie inne kontenery na koncie magazynu.

Podczas publikowania zdarzeń w tematach niestandardowych utwórz tematy dla Twoich zdarzeń, które ułatwiają subskrybentom sprawdzenie, czy są zainteresowani wydarzeniem. Subskrybenci używają właściwości tematu do filtrowania i kierowania zdarzeń. Rozważ dodanie ścieżki do miejsca wystąpienia zdarzenia, aby subskrybenci mogli filtrować według segmentów tej ścieżki. Ścieżka umożliwia subskrybentom filtrowanie zdarzeń wąsko lub szeroko. Jeśli podasz trzy ścieżki segmentu, takie jak /A/B/C w temacie, subskrybenci będą mogli filtrować według pierwszego segmentu /A , aby uzyskać szeroki zestaw zdarzeń. Ci subskrybenci otrzymują zdarzenia z tematami takimi jak /A/B/C lub /A/D/E. Inni subskrybenci mogą filtrować /A/B , aby uzyskać węższy zestaw zdarzeń.

Przykłady (zdarzenia usługi Blob Storage)

Zdarzenia obiektów blob można filtrować według typu zdarzenia, nazwy kontenera lub nazwy obiektu, który został utworzony lub usunięty.

Temat zdarzeń usługi Blob Storage używa formatu:

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

Aby dopasować wszystkie zdarzenia dla konta magazynu, można pozostawić puste filtry tematu.

Aby dopasować zdarzenia z obiektów blob utworzonych w zestawie kontenerów współużytkowania prefiksu, użyj filtru, subjectBeginsWith takiego jak:

/blobServices/default/containers/containerprefix

Aby dopasować zdarzenia z obiektów blob utworzonych w określonym kontenerze, użyj filtru, subjectBeginsWith takiego jak:

/blobServices/default/containers/containername/

Aby dopasować zdarzenia z obiektów blob utworzonych w określonym kontenerze współużytkowania prefiksu nazwy obiektu blob, użyj filtru, subjectBeginsWith takiego jak:

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

Aby dopasować zdarzenia z obiektów blob utworzonych w określonym podfolderze kontenera, użyj filtru, subjectBeginsWith takiego jak:

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

Aby dopasować zdarzenia z obiektów blob utworzonych w określonym kontenerze współużytkowania sufiksu obiektu blob, użyj filtru subjectEndsWith takiego jak ".log" lub ".jpg".

Filtrowanie zaawansowane

Aby filtrować według wartości w polach danych i określić operator porównania, użyj opcji zaawansowanego filtrowania. W zaawansowanym filtrowaniu należy określić następujące elementy:

typ operatora — typ porównania.
key — pole w danych zdarzenia, których używasz do filtrowania. Może to być liczba, wartość logiczna, ciąg lub tablica.
values — wartość lub wartości do porównania z kluczem.

Klucz

Klucz to pole w danych zdarzenia, których używasz do filtrowania. Może to być jeden z następujących typów:

Liczba
Wartość logiczna
String

Tablica. Aby użyć tej funkcji, należy ustawić enableAdvancedFilteringOnArrays właściwość na true.

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

W przypadku zdarzeń w schemacie Zdarzenia w chmurze użyj następujących wartości dla klucza: eventid, , sourceeventtype, eventtypeversionlub danych zdarzeń (takich jak data.key1).

Jeśli używasz warstwy podstawowej usługi Event Grid, w przypadku zdarzeń w schemacie usługi Event Grid użyj następujących wartości dla klucza: ID, TopicDataVersionSubjectEventTypelub danych zdarzeń (takich jak ).data.key1 W przypadku niestandardowego schematu danych wejściowych użyj pól danych zdarzenia (na przykład data.key1). Aby uzyskać dostęp do pól w sekcji danych, użyj . notacji (kropka). Na przykład , data.siteNamedata.appEventTypeDetail.action aby uzyskać dostęp do siteName następującego przykładowego zdarzenia lub action dla następującego przykładowego zdarzenia.

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

Uwaga

Usługa Event Grid nie obsługuje filtrowania w tablicy obiektów. Zezwala tylko na typy String, Boolean, Numbers i Array (na przykład tablica całkowita lub tablica ciągów).

Wartości

Wartości mogą być następujące: liczba, ciąg, wartość logiczna lub tablica

Operatory

Dostępne operatory dla liczb to:

NumberIn

Operator NumberIn zwraca wartość true, jeśli wartość klucza jest jedną z określonych wartości filtru . W poniższym przykładzie sprawdza, czy wartość atrybutu counter w data sekcji wynosi 5 lub 1.

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

Jeśli klucz jest tablicą, wszystkie wartości w tablicy są sprawdzane względem tablicy wartości filtru. Oto kod pseudo z kluczem: [v1, v2, v3] i filtr: [a, b, c]. Wszystkie wartości klucza z typami danych, które nie są zgodne z typem danych filtru, są ignorowane.

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

NumberNotIn

Wartość NumberNotIn daje wartość true, jeśli wartość klucza nie jest żadną z określonych wartości filtru. W poniższym przykładzie sprawdza, czy wartość atrybutu counter w data sekcji nie wynosi 41 i 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

Operator NumberLessThan daje wartość true, jeśli wartość klucza jest mniejsza niż określona wartość filtru . W poniższym przykładzie sprawdza, czy wartość atrybutu counter w data sekcji jest mniejsza niż 100.

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

Jeśli klucz jest tablicą, wszystkie wartości w tablicy są sprawdzane względem wartości filtru. Oto pseudo kod z kluczem: [v1, v2, v3]. Wszystkie wartości klucza z typami danych, które nie są zgodne z typem danych filtru, są ignorowane.

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

NumberGreaterThan

Operator NumberGreaterThan daje wartość true, jeśli wartość klucza jest większa niż określona wartość filtru . W poniższym przykładzie sprawdza, czy wartość atrybutu counter w data sekcji jest większa niż 20.

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

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

NumberLessThanOrEquals

Operator NumberLessThanOrEquals zwraca wartość true, jeśli wartość klucza jest mniejsza lub równa określonej wartości filtru . W poniższym przykładzie sprawdza, czy wartość atrybutu counter w data sekcji jest mniejsza lub równa 100.

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

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

NumberGreaterThanOrEquals

Operator NumberGreaterThanOrEquals zwraca wartość true, jeśli wartość klucza jest większa lub równa określonej wartości filtru . W poniższym przykładzie sprawdza, czy wartość atrybutu counter w data sekcji jest większa lub równa 30.

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

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

NumberInRange

Operator NumberInRange daje wartość true, jeśli wartość klucza znajduje się w jednym z określonych zakresów filtrów. W poniższym przykładzie sprawdza, czy wartość atrybutu key1 w data sekcji znajduje się w jednym z dwóch zakresów: 3.14159 - 999.95, 3000 - 4000.

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

Właściwość values jest tablicą zakresów. W poprzednim przykładzie jest to tablica dwóch zakresów. Oto przykład tablicy z jednym zakresem do sprawdzenia.

Tablica z jednym zakresem:

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

Jeśli klucz jest tablicą, wszystkie wartości w tablicy są sprawdzane względem tablicy wartości filtru. Oto pseudo kod z kluczem: [v1, v2, v3] i filtr: tablica zakresów. W tym pseudokodze a i b są niskimi i wysokimi wartościami każdego zakresu w tablicy. Wszystkie wartości klucza z typami danych, które nie są zgodne z typem danych filtru, są ignorowane.

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

NumberNotInRange

Operator NumberNotInRange daje wartość true, jeśli wartość klucza nie znajduje się w żadnym z określonych zakresów filtrów. W poniższym przykładzie sprawdza, czy wartość atrybutu key1 w data sekcji znajduje się w jednym z dwóch zakresów: 3.14159 - 999.95, 3000 - 4000. Jeśli tak jest, operator zwraca wartość false.

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

Właściwość values jest tablicą zakresów. W poprzednim przykładzie jest to tablica dwóch zakresów. Oto przykład tablicy z jednym zakresem do sprawdzenia.

Tablica z jednym zakresem:

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

Dostępny operator wartości logicznych to:

BoolEquals

Operator BoolEquals daje wartość true, jeśli wartość klucza jest określonym filtrem wartości logicznej. W poniższym przykładzie sprawdza, czy wartość atrybutu isEnabled w data sekcji to true.

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

Jeśli klucz jest tablicą, wszystkie wartości w tablicy są sprawdzane względem wartości logicznej filtru. Oto pseudo kod z kluczem: [v1, v2, v3]. Wszystkie wartości klucza z typami danych, które nie są zgodne z typem danych filtru, są ignorowane.

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

Dostępne operatory dla ciągów to:

CiągContains

Wartość StringContains daje wartość true, jeśli wartość klucza zawiera dowolną z określonych wartości filtru (jako podciąg). W poniższym przykładzie sprawdza, czy wartość atrybutu key1 w data sekcji zawiera jeden z określonych podciągów: microsoft lub azure. Na przykład azure data factory ma azure w nim wartość .

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