了解適用於事件格線訂用帳戶的事件篩選

發行項
04/18/2024

本文說明篩選要傳送至端點之事件的不同方式。建立事件訂閱時，您有三個選項可供篩選:

事件類型
主旨開頭或結尾為
進階欄位和運算子

Azure Resource Manager 範本

本文所示的範例是 JSON 程式碼片段，可用來定義 Azure Resource Manager (ARM) 範本中的篩選條件。如需完整 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 的主旨，以取得儲存體帳戶中該容器的所有事件，但不會取得其他容器中的事件。

當您發佈事件至自訂主題時，請為您的事件建立主題，讓訂閱者能輕鬆得知他們對事件是否感興趣。訂閱者可使用 subject 屬性篩選和路由事件。請考慮新增事件發生之位置的路徑，以便訂閱者可以根據該路徑的區段進行篩選。路徑可讓訂閱者縮小或擴大篩選事件。如果您在主旨中提供三區段路徑 (例如 /A/B/C)，訂閱者可根據第一個區段 /A 進行篩選，以取得一組廣泛的事件。這些訂閱者會取得包含如 /A/B/C 或 /A/D/E 等主旨的事件。其他訂閱者可依 /A/B 進行篩選，以取得一組較精簡的事件。

範例 (Blob 儲存體事件)

可以篩選 Blob 事件，可用的篩選依據包括事件類型、容器名稱、建立或刪除之物件的名稱。

Blob 儲存體事件的主體使用格式：

/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"。

進階篩選

若要依資料欄位中的值進行篩選，並指定比較運算子，請使用進階篩選選項。在進階篩選中，您可以指定:

運算子類型 - 比較的類型。
索引鍵 - 您用於篩選的事件資料中的欄位。它可以是數字、布林值、字串或陣列。
值 - 要和索引鍵比較的一或多個值。

機碼

索引鍵是事件資料中用來進行篩選的欄位。可以是下列其中一個類型：

數值
布林值
String

陣列。您必須將 enableAdvancedFilteringOnArrays 屬性設定為 true，才能使用此功能。

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

針對雲端事件結構描述中的事件，請使用下列值作為索引鍵：eventid、source、eventtype、eventtypeversion，或事件資料 (如 data.key1)。

如果您使用 [事件方格] 基本層，針對事件方格結構描述中的事件，請使用下列值作為索引鍵：ID、Topic、Subject、EventType、DataVersion，或事件資料 (如 data.key1)。針對自訂輸入結構描述，請使用事件資料欄位 (例如 data.key1)。若要存取資料區段中的欄位，請使用 . (點) 標記法。例如，下列範例事件中的 data.siteName、data.appEventTypeDetail.action 以存取 siteName 或 action。

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

注意

[事件方格] 不支援篩選物件陣列。它僅允許字串、布林值、數值，和相同類型的陣列 (例如整數陣列或字串陣列)。

值

值可以是：數字、字串、布林值或陣列

操作員

適用於數字的可用運算子為：

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