了解事件网格订阅的事件筛选Understand event filtering for Event Grid subscriptions

本本介绍了筛选发送到终结点的事件的不同方法。This article describes the different ways to filter which events are sent to your endpoint. 创建事件订阅时,有三个筛选选项:When creating an event subscription, you have three options for filtering:

  • 事件类型Event types
  • 主题开头内容或结尾内容Subject begins with or ends with
  • 高级字段和运算符Advanced fields and operators

事件类型筛选Event type filtering

默认情况下,事件源的所有事件类型都将发送到终结点。By default, all event types for the event source are sent to the endpoint. 可以决定仅将某些事件类型发送到终结点。You can decide to send only certain event types to your endpoint. 例如,可以收到有关资源更新的通知,但不会收到删除等其他操作的通知。For example, you can get notified of updates to your resources, but not notified for other operations like deletions. 在这种情况下,按 Microsoft.Resources.ResourceWriteSuccess 事件类型进行筛选。In that case, filter by the Microsoft.Resources.ResourceWriteSuccess event type. 提供包含事件类型的数组或指定 All 以获取事件源的所有事件类型。Provide an array with the event types, or specify All to get all event types for the event source.

按事件类型筛选的 JSON 语法是:The JSON syntax for filtering by event type is:

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

主题筛选Subject filtering

对于按主题的简单筛选,请指定主题的开头值或结尾值。For simple filtering by subject, specify a starting or ending value for the subject. 例如,可以使用 .txt 指定主题的结尾,以仅获取与将文本文件上传到存储帐户相关的事件。For example, you can specify the subject ends with .txt to only get events related to uploading a text file to storage account. 或者,可以筛选以 /blobServices/default/containers/testcontainer 开头的主题以获取该容器的所有事件,但不获取存储帐户中的其他容器。Or, you can filter the subject begins with /blobServices/default/containers/testcontainer to get all events for that container but not other containers in the storage account.

将事件发布到自定义主题时,可为事件创建主题,便于订阅者们了解他们是否对该事件感兴趣。When publishing events to custom topics, create subjects for your events that make it easy for subscribers to know whether they're interested in the event. 订阅者使用主题属性来筛选和路由事件。Subscribers use the subject property to filter and route events. 考虑添加事件发生位置的路径,以便订阅者可以按该路径的段进行筛选。Consider adding the path for where the event happened, so subscribers can filter by segments of that path. 通过路径,订阅者可精确或宽泛地筛选事件。The path enables subscribers to narrowly or broadly filter events. 如果在主题中提供一个由三个段构成的路径(如 /A/B/C),订阅者可根据第一个段 /A 进行筛选,获取范围较宽泛的一组事件。If you provide a three segment path like /A/B/C in the subject, subscribers can filter by the first segment /A to get a broad set of events. 这些订阅者会获取主题为 /A/B/C/A/D/E 这样的事件。Those subscribers get events with subjects like /A/B/C or /A/D/E. 其他订阅者可通过 /A/B 进行筛选,这样可以获取范围更精确的一组事件。Other subscribers can filter by /A/B to get a narrower set of events.

按主题筛选的 JSON 语法是:The JSON syntax for filtering by subject is:

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

高级筛选Advanced filtering

要按数据字段中的值进行筛选并指定比较运算符,请使用高级筛选选项。To filter by values in the data fields and specify the comparison operator, use the advanced filtering option. 在高级筛选中,指定:In advanced filtering, you specify the:

  • 运算符类型 - 比较的类型。operator type - The type of comparison.
  • 键 - 用于筛选的事件数据中的字段。key - The field in the event data that you're using for filtering. 它可以是数字、布尔值或字符串。It can be a number, boolean, or string.
  • 值 - 要与键进行比较的值。value or values - The value or values to compare to the key.

如果指定具有多个值的单个筛选器,则将执行 OR 操作,因此键字段的值必须是这些值之一。If you specify a single filter with multiple values, an OR operation is performed, so the value of the key field must be one of these values. 以下是示例:Here is an example:

"advancedFilters": [
    {
        "operatorType": "StringContains",
        "key": "Subject",
        "values": [
            "/providers/microsoft.devtestlab/",
            "/providers/Microsoft.Compute/virtualMachines/"
        ]
    }
]

如果指定多个不同的筛选器,则将执行 AND 操作,因此必须满足每个筛选器条件。If you specify multiple different filters, an AND operation is performed, so each filter condition must be met. 以下是示例:Here is an example:

"advancedFilters": [
    {
        "operatorType": "StringContains",
        "key": "Subject",
        "values": [
            "/providers/microsoft.devtestlab/"
        ]
    },
    {
        "operatorType": "StringContains",
        "key": "Subject",
        "values": [
            "/providers/Microsoft.Compute/virtualMachines/"
        ]
    }
]

运算符Operator

可用的数字运算符为:The available operators for numbers are:

  • NumberGreaterThanNumberGreaterThan
  • NumberGreaterThanOrEqualsNumberGreaterThanOrEquals
  • NumberLessThanNumberLessThan
  • NumberLessThanOrEqualsNumberLessThanOrEquals
  • NumberInNumberIn
  • NumberNotInNumberNotIn

可用的布尔值运算符为:BoolEqualsThe available operator for booleans is: BoolEquals

可用的字符串运算符为:The available operators for strings are:

  • StringContainsStringContains
  • StringBeginsWithStringBeginsWith
  • StringEndsWithStringEndsWith
  • StringInStringIn
  • StringNotInStringNotIn

所有字符串比较都不区分大小写。All string comparisons are case-insensitve.

Key

对于事件网格架构中的事件,请使用以下键值:For events in the Event Grid schema, use the following values for the key:

  • IDId
  • 主题Topic
  • 使用者Subject
  • EventTypeEventType
  • DataVersionDataVersion
  • 事件数据(如 Data.key1)Event data (like Data.key1)

对于云事件架构中的事件,请使用以下键值:For events in Cloud Events schema, use the following values for the key:

  • EventIdEventId
  • SourceSource
  • EventTypeEventType
  • EventTypeVersionEventTypeVersion
  • 事件数据(如 Data.key1)Event data (like Data.key1)

对于自定义输入架构,请使用事件数据字段(如 Data.key1)。For custom input schema, use the event data fields (like Data.key1).

Values

值可以是:The values can be:

  • numbernumber
  • stringstring
  • 布尔值boolean
  • arrayarray

限制Limitations

高级筛选具有以下限制:Advanced filtering has the following limitations:

  • 每个事件网格订阅有五个高级筛选器Five advanced filters per event grid subscription
  • 每个字符串值有 512 个字符512 characters per string value
  • “in”和“not in”运算符有 5 个值 Five values for in and not in operators

可以在多个筛选器中使用相同的键。The same key can be used in more than one filter.

后续步骤Next steps