Azure Event Grid 名前空間のトピックへのサブスクリプションのイベントフィルター

この記事では、名前空間トピックへのイベントサブスクリプションにフィルターを指定するさまざまな方法について説明します。フィルターを使用すると、パブリッシャーが Event Grid に送信先エンドポイントに送信するイベントのサブセットのみを送信できます。イベントサブスクリプションを作成する場合、フィルター処理には次の 3 つのオプションがあります。

イベントの種類
件名は次で始まるか、または終わる
高度なフィールドと演算子

イベントの種類のフィルター処理

既定では、イベントソースのすべてのイベントの種類がエンドポイントに送信されます。エンドポイントに送信できるのは、特定のイベントの種類のみです。たとえば、リソースの更新の通知を受け取ることができますが、削除などの他の操作については通知されません。その場合は、 Microsoft.Resources.ResourceWriteSuccess イベントの種類でフィルター処理します。イベントの種類を配列に指定するか、イベントソースのすべてのイベントの種類を取得する All を指定します。

イベントの種類によるフィルター処理の JSON 構文は次のとおりです。

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

件名のフィルター処理

件名による単純なフィルター処理の場合は、件名の開始値または終了値を指定します。たとえば、ストレージアカウントへのテキストファイルのアップロードに関連するイベントのみを取得するために、件名を .txt で終了するように指定できます。または、 /blobServices/default/containers/testcontainer で始まる件名をフィルター処理して、ストレージアカウント内の他のコンテナーではなく、そのコンテナーのすべてのイベントを取得できます。

カスタムトピックにイベントを発行する場合は、イベントの件名を作成して、サブスクライバーがイベントに関心があるかどうかを簡単に把握できるようにします。サブスクライバーは 、subject プロパティを使用してイベントをフィルター処理およびルーティングします。サブスクライバーがそのパスのセグメントでフィルター処理できるように、イベントが発生した場所のパスを追加することを検討してください。このパスを使用すると、サブスクライバーはイベントを絞り込んだり、広くフィルター処理したりできます。件名に /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 からのイベントを照合するには、".log" や ".jpg" などの subjectEndsWith フィルターを使用します。

高度なフィルター処理

データフィールドの値でフィルター処理し、比較演算子を指定するには、高度なフィルター処理オプションを使用します。高度なフィルター処理では、次の項目を指定します。

演算子の型 - 比較の型。
key - フィルター処理に使用するイベントデータのフィールド。数値、ブール値、文字列、または配列を指定できます。
values - キーと比較する値。

Key

キーは、フィルター処理に使用するイベントデータのフィールドです。次のいずれかの種類を指定できます。

Number
ブール値
String

配列。この機能を使用するには、 enableAdvancedFilteringOnArrays プロパティを true に設定する必要があります。

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

Cloud Events スキーマのイベントの場合は、キーに次の値を使用します:eventid、source、eventtype、eventtypeversion、またはイベントデータ (data.key1 など)。

Event Grid の基本レベルを使用している場合は、 Event Grid スキーマのイベントに対して、キーに ID、 Topic、 Subject、 EventType、 DataVersion、またはイベントデータ ( data.key1 など) の値を使用します。 カスタム入力スキーマの場合は、イベントデータフィールド (data.key1 など) を使用します。データセクションのフィールドにアクセスするには、 . (ドット) 表記を使用します。たとえば、data.siteName、次のサンプルイベントのsiteNameまたはactionにアクセスする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 の 2 つの範囲のいずれかに含まれているかどうかを確認します。

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

values プロパティは範囲の配列です。前の例では、2 つの範囲の配列です。チェックする範囲が 1 つの配列の例を次に示します。

1 つの範囲を持つ配列:

{
    "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 の 2 つの範囲のいずれかに含まれているかどうかを確認します。その場合、演算子は false を返します。

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

values プロパティは範囲の配列です。前の例では、2 つの範囲の配列です。チェックする範囲が 1 つの配列の例を次に示します。

1 つの範囲を持つ配列:

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