Event Grid 구독에 대한 이벤트 필터링 이해

아티클
02/23/2024

이 문서에서는 엔드포인트에 전송되는 이벤트를 필터링하는 다양한 방법을 설명합니다. 이벤트 구독을 만들 때 필터링에 대한 세 가지 옵션이 있습니다.

일정 유형
다음 값으로 시작하거나 끝나는 제목
고급 필드 및 연산자

Azure Resource Manager 템플릿

이 문서에 표시된 예제는 ARM(Azure Resource Manager) 템플릿에서 필터를 정의하기 위한 JSON 코드 조각입니다. 전체 ARM 템플릿 및 ARM 템플릿 배포의 예제는 빠른 시작: ARM 템플릿을 사용하여 Blob 스토리지 이벤트를 웹 엔드포인트로 라우팅을 참조하세요. 다음은 빠른 시작 예제의 filter 섹션에 대한 몇 가지 추가 섹션입니다. ARM 템플릿은 다음 리소스를 정의합니다.

Azure Storage 계정
스토리지 계정에 대한 시스템 항목
시스템 항목에 대한 이벤트 구독입니다. 이벤트 구독 섹션에 filter 하위 섹션이 표시됩니다.

다음 예제에서 이벤트 구독은 Microsoft.Storage.BlobCreated 및 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'))]"
      ]
    }
  ]
}

이벤트 유형 필터링

기본적으로 이벤트 원본에 대한 모든 이벤트 유형은 엔드포인트로 전송됩니다. 특정 이벤트 유형만 엔드포인트에 보내도록 결정할 수 있습니다. 예를 들어 리소스에 대한 업데이트 알림을 받을 수 있지만 삭제와 같은 다른 작업에 대한 알림을 받을 수 없습니다. 이런 경우 Microsoft.Resources.ResourceWriteSuccess 이벤트 유형별로 필터링합니다. 이벤트 유형으로 배열을 제공하거나 이벤트 원본에 대한 모든 이벤트 유형을 가져오도록 All을 지정합니다.

이벤트 유형별로 필터링에 대한 JSON 구문은 다음과 같습니다.

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

제목 필터링

제목별 간단한 필터링을 위해 제목에 대한 시작 또는 끝 값을 지정합니다. 예를 들어 .txt로 끝나는 제목을 지정하여 스토리지 계정에 텍스트 파일 업로드와 관련된 이벤트만을 가져올 수 있습니다. 또는 /blobServices/default/containers/testcontainer로 시작하는 제목을 필터링하여 스토리지 계정에 다른 컨테이너가 아닌 해당 컨테이너에 대한 모든 이벤트를 가져올 수 있습니다.

사용자 지정 항목에 이벤트를 게시할 때 구독자가 이벤트에 관심이 있는지 더 쉽게 알 수 있도록 사용자 이벤트에 대한 제목을 만듭니다. 구독자는 제목 속성을 사용하여 이벤트를 필터링 및 라우팅합니다. 구독자가 해당 경로의 세그먼트를 기준으로 필터링할 수 있도록 이벤트가 발생하는 경로를 추가하는 것을 고려합니다. 구독자는 경로를 통해 이벤트를 제한적이거나 광범위하게 필터링할 수 있습니다. 제목에 /A/B/C와 같은 3개의 세그먼트 경로를 제공하는 경우 구독자는 첫 번째 세그먼트 /A를 기준으로 필터링하여 광범위한 이벤트 집합을 가져올 수 있습니다. 구독자는 /A/B/C 또는 /A/D/E와 같은 제목이 있는 이벤트를 가져옵니다. 다른 구독자는 /A/B를 기준으로 필터링하여 제한된 이벤트 집합을 얻을 수 있습니다.

예(Blob Storage 이벤트)

이벤트 유형, 컨테이너 이름 또는 생성 또는 삭제된 개체의 이름에 따라 Blob 이벤트를 필터링할 수 있습니다.

Blob Storage 이벤트의 제목은 다음 형식을 사용합니다.

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

스토리지 계정의 모든 이벤트와 일치하는 항목을 찾으려면 제목 필터를 비워 둡니다.

접두사를 공유하는 컨테이너 집합에서 생성된 Blob의 이벤트와 일치하는 항목을 찾으려면 다음과 같은 subjectBeginsWith 필터를 사용합니다.

/blobServices/default/containers/containerprefix

특정 컨테이너에서 생성된 Blob의 이벤트와 일치하는 항목을 찾으려면 다음과 같은 subjectBeginsWith 필터를 사용합니다.

/blobServices/default/containers/containername/

Blob 이름 접두사를 공유하는 특정 컨테이너에서 생성된 Blob의 이벤트와 일치하는 항목을 찾으려면 다음과 같은 subjectBeginsWith 필터를 사용합니다.

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

컨테이너의 특정 하위 폴더에 만들어진 Blob의 이벤트를 일치시키려면 다음과 같은 subjectBeginsWith 필터를 사용합니다.

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

Blob 접미사를 공유하는 특정 컨테이너에 만들어진 Blob의 이벤트와 일치시키려면 subjectEndsWith 필터(예: ".log" 또는 ".jpg")를 사용합니다.

고급 필터링

데이터 필드에서 값을 기준으로 필터링하고 비교 연산자를 지정하려면 고급 필터링 옵션을 사용합니다. 고급 필터링에서 다음을 지정합니다.

연산자 형식 - 비교의 형식입니다.
키 - 필터링에 사용하는 이벤트 데이터의 필드입니다. 숫자, 부울, 문자열 또는 배열일 수 있습니다.
값 - 키와 비교할 값입니다.

키

키는 필터링에 사용하는 이벤트 데이터의 필드입니다. 다음 유형 중 하나일 수 있습니다.

숫자
부울
문자열

배열. 이 기능을 사용하려면 enableAdvancedFilteringOnArrays 속성을 true로 설정해야 합니다.

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

클라우드 이벤트 스키마의 이벤트의 경우에는 키에 eventid, source, eventtype, eventtypeversion 값 또는 이벤트 데이터(예: data.key1)를 사용합니다.

Event Grid 기본 계층을 사용하는 경우 Event Grid 스키마의 이벤트의 경우에는 키에 ID, Topic, Subject, EventType, DataVersion 값 또는 이벤트 데이터(예: data.key1)를 사용합니다. 사용자 지정 입력 스키마의 경우 이벤트 데이터 필드(예: data.key1)를 사용합니다. 데이터 섹션의 필드에 액세스하려면 .(점) 표기법을 사용합니다. 예를 들어 다음 샘플 이벤트에 대해 siteName 또는 action에 액세스하려면 data.siteName, data.appEventTypeDetail.action을 사용합니다.

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

참고 항목

Event Grid는 개체 배열에 대한 필터링을 지원하지 않습니다. 동일한 형식의 문자열, 부울, 숫자 및 배열(예: 정수 배열 또는 문자열 배열)만 허용됩니다.

값

값은 숫자, 문자열, 부울 또는 배열일 수 있습니다.

연산자

숫자에 사용 가능한 연산자는 다음과 같습니다.

NumberIn

NumberIn 연산자는 키 값이 지정된 필터 값 중 하나이면 true로 평가됩니다. 다음 예제에서는 data 섹션에서 counter 특성의 값이 5 또는 1인지 여부를 확인합니다.

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

키가 배열이면 배열의 모든 값이 필터 값의 배열에 따라 확인됩니다. 키: [v1, v2, v3] 및 필터: [a, b, c]의 의사 코드는 다음과 같습니다. 필터의 데이터 형식과 일치하지 않는 데이터 형식의 키 값은 무시됩니다.

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

NumberNotIn

NumberNotIn은 키 값이 지정된 필터 값이 아닐 때 true로 평가됩니다. 다음 예제에서는 data 섹션에서 counter 특성의 값이 41 및 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

NumberLessThan 연산자는 키 값이 지정된 필터 값보다 작을 때 true로 평가됩니다. 다음 예제에서는 data 섹션에서 counter 특성의 값이 100보다 작은지 여부를 확인합니다.

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

키가 배열이면 배열의 모든 값이 필터에 따라 확인됩니다. 키: [v1, v2, v3]가 포함된 의사 코드는 다음과 같습니다. 필터의 데이터 형식과 일치하지 않는 데이터 형식의 키 값은 무시됩니다.

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

NumberGreaterThan

NumberGreaterThan 연산자는 키 값이 지정된 필터 값보다 클 때 true로 평가됩니다. 다음 예제에서는 data 섹션에서 counter 특성의 값이 20보다 큰지 여부를 확인합니다.

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

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

NumberLessThanOrEquals

NumberLessThanOrEquals 연산자는 키 값이 지정된 필터 값보다 작거나 같을 때 true로 평가됩니다. 다음 예제에서는 data 섹션에서 counter 특성의 값이 100보다 작거나 같은지 여부를 확인합니다.

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

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

NumberGreaterThanOrEquals

NumberGreaterThanOrEquals 연산자는 키 값이 지정된 필터 값보다 크거나 같을 때 true로 평가됩니다. 다음 예제에서는 data 섹션에서 counter 특성의 값이 30보다 크거나 같은지 여부를 확인합니다.

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

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

NumberInRange

NumberInRange 연산자는 키 값이 지정된 필터 범위 중 하나에 있으면 true로 평가됩니다. 다음 예제에서는 data 섹션에서 key1 특성의 값이 3.14159 - 999.95, 3000 - 4000의 두 범위 중 하나에 있는지 여부를 확인합니다.

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

values 속성은 배열 범위입니다. 이전 예제에서는 두 범위의 배열입니다. 확인할 범위가 하나인 배열 예제는 다음과 같습니다.

범위가 하나인 배열:

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

키가 배열이면 배열의 모든 값이 필터 값의 배열에 따라 확인됩니다. 키: [v1, v2, v3] 및 필터: 범위의 배열이 사용되는 의사 코드는 다음과 같습니다. 이 의사 코드에서 a 및 b는 배열에 있는 각 범위의 낮은 값과 높은 값입니다. 필터의 데이터 형식과 일치하지 않는 데이터 형식의 키 값은 무시됩니다.

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

NumberNotInRange

NumberNotInRange 연산자는 키 값이 지정된 필터 범위에 없으면 true로 평가됩니다. 다음 예제에서는 data 섹션에서 key1 특성의 값이 3.14159 - 999.95, 3000 - 4000의 두 범위 중 하나에 있는지 여부를 확인합니다. 범위에 있으면 연산자가 false를 반환합니다.

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

values 속성은 배열 범위입니다. 이전 예제에서는 두 범위의 배열입니다. 확인할 범위가 하나인 배열 예제는 다음과 같습니다.

범위가 하나인 배열:

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

부울에 사용 가능한 연산자는 다음과 같습니다.

BoolEquals

BoolEquals 연산자는 키 값이 지정된 부울 값 필터이면 true로 평가됩니다. 다음 예제에서는 data 섹션에서 isEnabled 특성의 값이 true인지 여부를 확인합니다.

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

키가 배열이면 배열의 모든 값이 필터 부울 값에 따라 확인됩니다. 키: [v1, v2, v3]가 포함된 의사 코드는 다음과 같습니다. 필터의 데이터 형식과 일치하지 않는 데이터 형식의 키 값은 무시됩니다.

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

문자열에 사용 가능한 연산자는 다음과 같습니다.

StringContains

StringContains는 키 값에 지정된 필터 값(부분 문자열)이 포함되는 경우 true로 평가됩니다. 다음 예제에서는 data 섹션에서 key1 특성의 값이 지정된 부분 문자열 microsoft 또는 azure 중 하나를 포함하는지 여부를 확인합니다. 예를 들어 azure data factory에는 azure가 포함됩니다.

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