Memahami pemfilteran kejadian untuk langganan Azure Event Grid

Artikel
11/15/2023

Artikel ini menjelaskan berbagai cara untuk filter kejadian mana yang dikirim ke titik akhir Anda. Saat membuat langganan kejadian, Anda memiliki tiga opsi untuk memfilter:

Tipe peristiwa
Subjek dimulai dengan atau diakhiri dengan
Bidang dan operator tingkat lanjut

Templat Azure Resource Manager

Contoh yang ditunjukkan dalam artikel ini adalah cuplikan JSON untuk menentukan filter dalam templat Azure Resource Manager (ARM). Untuk contoh templat ARM lengkap dan penyebaran templat ARM, lihat Mulai Cepat: Merutekan peristiwa penyimpanan Blob ke titik akhir web menggunakan templat ARM. Berikut beberapa bagian lainnya di sekitar bagian filter dari contoh dalam mulai cepat. Templat ARM menentukan sumber daya berikut.

Akun penyimpanan Azure
Topik sistem untuk akun penyimpanan
Langganan peristiwa untuk topik sistem. Anda akan melihat subbagian filter di bagian langganan peristiwa.

Dalam contoh berikut, langganan peristiwa memfilter peristiwa Microsoft.Storage.BlobCreated dan Microsoft.Storage.BlobDeleted.

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

Pemfilteran jenis kejadian

Secara default, semua jenis kejadian untuk sumber kejadian dikirim ke titik akhir. Anda dapat memutuskan untuk mengirim hanya jenis kejadian tertentu ke titik akhir Anda. Misalnya, Anda bisa mendapatkan pemberitahuan pembaruan untuk sumber daya Anda, tetapi tidak diberi tahu untuk operasi lain seperti penghapusan. Dalam hal ini, filter menurut Microsoft.Resources.ResourceWriteSuccess jenis kejadian. Sediakan array dengan jenis kejadian, atau tentukan All untuk mendapatkan semua jenis kejadian untuk sumber kejadian.

Sintaksis JSON untuk pemfilteran menurut jenis kejadian adalah:

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

Pemfilteran subjek

Untuk pemfilteran sederhana menurut subjek, tentukan nilai awal atau akhir untuk subjek. Misalnya, Anda dapat menentukan subjek yang diakhiri .txt untuk hanya mendapatkan kejadian yang terkait dengan mengunggah file teks ke akun penyimpanan. Atau, Anda dapat memfilter subjek dimulai untuk /blobServices/default/containers/testcontainer mendapatkan semua kejadian untuk kontainer itu tetapi bukan kontainer lain di akun penyimpanan.

Saat menerbitkan kejadian ke topik khusus, buat subjek untuk kejadian Anda yang memudahkan pelanggan untuk mengetahui apakah mereka tertarik dengan kejadian tersebut. Pelanggan menggunakan properti subjek untuk memfilter dan merutekan peristiwa. Pertimbangkan untuk menambahkan jalur tempat kejadian terjadi, sehingga pelanggan dapat memfilter berdasarkan segmen jalur tersebut. Jalur ini memungkinkan pelanggan untuk memfilter kejadian secara sempit atau luas. Jika Anda menyediakan jalur tiga segmen seperti dalam /A/B/C subjek, pelanggan dapat memfilter berdasarkan segmen pertama /A untuk mendapatkan serangkaian kejadian yang luas. Pelanggan tersebut mendapatkan peristiwa dengan subjek seperti /A/B/C atau /A/D/E. Pelanggan lain dapat memfilter berdasarkan /A/B untuk mendapatkan set peristiwa yang lebih sempit.

Contoh (peristiwa Blob Storage)

Peristiwa blob dapat difilter menurut jenis peristiwa, nama kontainer, atau nama objek yang dibuat atau dihapus.

Subjek kejadian penyimpanan Blob menggunakan format:

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

Untuk mencocokkan semua kejadian akun penyimpanan, Anda dapat membiarkan filter subjek kosong.

Untuk mencocokkan kejadian dari blob yang dibuat dalam sekumpulan kontainer berimbuhan sama, gunakan filter subjectBeginsWith seperti:

/blobServices/default/containers/containerprefix

Untuk mencocokkan kejadian dari blob yang dibuat dalam kontainer tertentu, gunakan filter subjectBeginsWith seperti:

/blobServices/default/containers/containername/

Untuk mencocokkan kejadian dari blob yang dibuat dalam kontainer berimbuhan nama blob sama, gunakan filter subjectBeginsWith seperti:

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

Untuk mencocokkan peristiwa dari blob yang dibuat di subfolder kontainer tertentu, gunakan subjectBeginsWith filter seperti:

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

Untuk mencocokkan kejadian dari blob yang dibuat dalam kontainer berimbuhan blob sama, gunakan filter subjectEndsWith seperti ".log" atau ".jpg".

Pemfilteran tingkat lanjut

Untuk memfilter menurut nilai di bidang data dan menentukan operator perbandingan, gunakan opsi pemfilteran tingkat lanjut. Dalam pemfilteran tingkat lanjut, Anda menentukan:

jenis operator - Jenis perbandingan.
key - Bidang dalam data kejadian yang Anda gunakan untuk pemfilteran. Ini bisa menjadi angka, boolean, string, atau array.
nilai - Nilai atau nilai untuk dibandingkan dengan kunci.

Tombol

key - Bidang dalam data kejadian yang Anda gunakan untuk pemfilteran. Hal ini dapat berupa salah satu dari jenis berikut:

Angka
Boolean
String

Array. Anda perlu mengatur enableAdvancedFilteringOnArrays properti ke true untuk menggunakan fitur ini.

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

Untuk kejadian dalam skema Events Cloud, gunakan nilai berikut untuk kunci: eventid, source, eventtype, eventtypeversion, atau data kejadian (seperti data.key1).

Jika Anda menggunakan tingkat dasar Event Grid, untuk peristiwa dalam skema Event Grid, gunakan nilai berikut untuk kunci: ID, , Topic, EventTypeSubject, DataVersionatau data peristiwa (seperti data.key1). Untuk skema input kustom, gunakan bidang data kejadian (seperti data.key1). Untuk mengakses bidang di bagian data, gunakan . notasi (titik). Misalnya, data.siteName, data.appEventTypeDetail.action untuk mengakses siteName atau action untuk contoh kejadian berikut.

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

Catatan

Event Grid tidak mendukung pemfilteran pada array objek. Ini hanya memungkinkan String, Boolean, Numbers, dan Array dari jenis yang sama (seperti array bilangan bulat atau array string).

Nilai

Nilainya bisa: angka, string, boolean, atau array

Operator

Operator yang tersedia untuk nomor adalah:

NumberIn

Operator NumberIn mengevaluasi ke true jika nilai kunci adalah salah satu nilai filter yang ditentukan. Dalam contoh berikut, ia memeriksa apakah nilai counter atribut dalam data bagian adalah 5 atau 1.

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

Jika kunci adalah array, semua nilai dalam array dicentang terhadap array nilai filter. Berikut adalah kode pseudo dengan kunci: [v1, v2, v3] dan filter: [a, b, c]. Nilai kunci apa pun dengan jenis data yang tidak cocok dengan jenis data filter diabaikan.

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

NumberNotIn

NumberNotIn mengevaluasi ke true jika nilai kunci bukan salah satu nilai filter yang ditentukan. Dalam contoh berikut, ia memeriksa apakah nilai counter atribut dalam data bagian adalah 41 atau 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 mengevaluasi ke true jika nilai kuncikurang dari nilai filter yang ditentukan. Dalam contoh berikut, ia memeriksa apakah nilai counter atribut dalam data bagian adalah 100 atau 1.

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

Jika kunci adalah array, semua nilai dalam array dicentang terhadap array nilai filter. Berikut kode pseudo dengan kunci: [v1, v2, v3]. Nilai kunci apa pun dengan jenis data yang tidak cocok dengan jenis data filter diabaikan.

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

NumberGreaterThan

Operator NumberGreaterThan mengevaluasi ke true jika nilai kuncilebih besar dari nilai filter yang ditentukan. Dalam contoh berikut, ia memeriksa apakah nilai counter atribut dalam data bagian adalah 20 atau 1.

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

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

NumberLessThanOrEquals

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

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

NumberLessThanOrEquals

Operator NumberGreaterThan mengevaluasi ke true jika nilai kuncilebih besar dari nilai filter yang ditentukan. Dalam contoh berikut, ini memeriksa apakah nilai counteratribut di data bagian lebih besar dari atau sama dengan 30.

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

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

NumberInRange

Operator NumberIn mengevaluasi ke true jika nilai kunci adalah salah satu nilai filter yang ditentukan. Dalam contoh berikut, ia memeriksa apakah nilai key1atribut di bagian data ada di salah satu dari dua rentang: 3.14159 - 999.95, 3000 - 4000.

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

Properti values adalah array rentang. Dalam contoh sebelumnya, ini adalah array dari dua rentang. Berikut ini contoh array dengan satu rentang untuk diperiksa.

Array dengan satu rentang:

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

Jika kunci adalah array, semua nilai dalam array dicentang terhadap array nilai filter. Berikut adalah kode pseudo dengan kunci: [v1, v2, v3] dan filter: array rentang. Dalam kode pseudo ini, a dan b adalah nilai rendah dan tinggi dari setiap rentang dalam array. Nilai kunci apa pun dengan jenis data yang tidak cocok dengan jenis data filter diabaikan.

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

NumberNotInRange

Operator NumberNotInRange mengevaluasi ke true jika nilai kunci tidak berada dalam salah satu rentang filter yang ditentukan. Dalam contoh berikut, ia memeriksa apakah nilai key1atribut di bagian data ada di salah satu dari dua rentang: 3.14159 - 999.95, 3000 - 4000. Jika ya, operator mengembalikan false.

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

Properti values adalah array rentang. Dalam contoh sebelumnya, ini adalah array dari dua rentang. Berikut ini contoh array dengan satu rentang untuk diperiksa.

Array dengan satu rentang:

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

Operator yang tersedia untuk booleans adalah:

BoolEquals

Operator BoolEquals mengevaluasi ke true jika nilai kuncinya adalah filter nilai boolean yang ditentukan. Dalam contoh berikut, ia memeriksa apakah nilai atribut isEnabled di bagian data adalah true.

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

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

Operator yang tersedia untuk string adalah:

StringContains

StringContains mengevaluasi ke true jika nilai kunci berisi salah satu nilai filter yang ditentukan (sebagai substring). Dalam contoh berikut, ia memeriksa apakah nilai key1 atribut dalam data bagian berisi salah satu substring yang ditentukan: microsoft atau azure. Misalnya, azure data factory ada di azure dalamnya.

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