了解事件网格订阅的事件筛选

2025-09-15

本本介绍了筛选发送到终结点的事件的不同方法。创建事件订阅时，有三个筛选选项：

事件类型
主题开头内容或结尾内容
高级字段和运算符

Azure Resource Manager 模板

本文所示的示例是 JSON 代码片段，用于在 Azure 资源管理器 (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 开头的主题以获取该容器的所有事件，但不获取存储帐户中的其他容器。

将事件发布到自定义主题时，可为事件创建主题，便于订阅者们了解他们是否对该事件感兴趣。订阅者将使用主题属性来筛选和路由事件。考虑添加事件发生位置的路径，以便订阅者可以按该路径的段进行筛选。通过路径，订阅者可精确或宽泛地筛选事件。如果在主题中提供一个由三个段构成的路径（如 /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”。

高级筛选

要按数据字段中的值进行筛选并指定比较运算符，请使用高级筛选选项。在高级筛选中，指定：

运算符类型 - 比较的类型。
键 - 用于筛选的事件数据中的字段。它可以是数字、布尔值、字符串或数组。
值 - 要与键进行比较的值。

密钥

键是用于筛选的事件数据中的字段。可以是下列类型之一：

Number
布尔
字符串

数组。需要将 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。在以下示例中，它将检查 counter 节中 data 特性的值是 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。在以下示例中，它将检查 counter 节中 data 特性的值是否不是 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。在以下示例中，它将检查 counter 节中 data 特性的值是否小于 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。在以下示例中，它将检查 counter 节中 data 特性的值是否大于 20。

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

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

NumberLessThanOrEquals

如果键值小于或等于指定的筛选器值，则 NumberLessThanOrEquals 运算符的计算结果为 true。在以下示例中，它将检查 counter 节中 data 特性的值是否小于或等于 100。

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

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

NumberGreaterThanOrEquals

如果键值大于或等于指定的筛选器值，则 NumberGreaterThanOrEquals 运算符的计算结果为 true。在以下示例中，它将检查 counter 节中 data 特性的值是否大于或等于 30。

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

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

NumberInRange

如果键值在指定的筛选器范围之一内，则 NumberInRange 运算符的计算结果为 true。在以下示例中，它将检查 key1 节中 data 特性的值是否在以下两个范围之内：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。在以下示例中，它将检查 key1 节中 data 特性的值是否在以下两个范围之内：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。在以下示例中，它将检查 isEnabled 节中 data 特性的值是否为 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。在以下示例中，它将检查 key1 节中 data 特性的值是否包含指定的子字符串之一：microsoft 或 azure。例如，azure data factory 中包含 azure。

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