Event Grid サブスクリプションでのイベントのフィルター処理を理解します

[アーティクル]
11/15/2023

この記事では、ご利用のエンドポイントに送信されるイベントをフィルター処理するさまざまな方法について説明します。イベントサブスクリプションを作成するとき、フィルター処理を行うためのオプションとして次の 3 つがあります。

イベントの種類
指定の値で開始または終了する件名
高度なフィールドおよび演算子

Azure Resource Manager テンプレート

この記事に示す例は、Azure Resource Manager (ARM) テンプレートでフィルターを定義するための JSON スニペットです。詳細な ARM テンプレートと ARM テンプレートのデプロイの例については、「クイックスタート: ARM テンプレートを使用して BLOB ストレージイベントを Web エンドポイントにルーティングする」を参照してください。クイックスタートの例の filter セクションに関するその他のセクションを以下に示します。 ARM テンプレートでは、次のリソースを定義します。

Azure ストレージアカウント
ストレージアカウントのシステムトピック
システムトピックのイベントサブスクリプション。イベントサブスクリプションセクションに 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 からのイベントと一致させるには、".log" や ".jpg" などの subjectEndsWith フィルターを使います。

高度なフィルター処理

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

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

Key

キーは、フィルター処理のために使用するイベントデータ内のフィールドです。これは、次のいずれかの型になります。

Number
Boolean
String

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

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

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

Event Grid Basic レベルを使用している場合、Event Grid スキーマ内のイベントには、キーの値として ID、Topic、Subject、EventType、DataVersion、またはイベントデータ (例: data.key1) を使用します。 カスタム入力スキーマの場合は、イベントデータフィールドを使用します (例: data.key1)。 data セクション内のフィールドにアクセスするには、. (ドット) 表記を使用します。たとえば、次のサンプルイベントの 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 の 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"
    ]
}]