Общие сведения о фильтрации событий для подписок на службу "Сетка событий Azure"

Статья
11/15/2023

В статье описываются различные способы фильтрации событий, отправляемых в конечную точку. При создании подписки на события предлагается три варианта фильтрации:

Типы событий
по тому, что находится в начале или конце темы;
с помощью расширенных полей и операторов.

Шаблон Azure Resource Manager

Представленные в этой статье примеры содержат фрагменты кода в формате JSON, которые определяют фильтры в шаблонах Azure Resource Manager (ARM). Полный пример шаблона ARM и инструкции по его развертыванию см. в статье Краткое руководство. Маршрутизация событий хранилища больших двоичных объектов в конечную веб-точку с помощью шаблона ARM. Ниже приведены еще несколько разделов, основанных на разделе 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>

Чтобы сопоставить все события для учетной записи хранения, фильтры темы можно оставить пустыми.

Чтобы сопоставить события из больших двоичных объектов, созданных в наборе контейнеров с общим префиксом, используйте фильтр subjectBeginsWith, подобный этому:

/blobServices/default/containers/containerprefix

Чтобы сопоставить события из больших двоичных объектов, созданных в конкретном контейнере, используйте фильтр subjectBeginsWith, подобный этому:

/blobServices/default/containers/containername/

Чтобы сопоставить события из больших двоичных объектов, созданных в конкретном контейнере с общим префиксом имени большого двоичного объекта, используйте фильтр subjectBeginsWith, подобный этому:

/blobServices/default/containers/containername/blobs/blobprefix

Чтобы сопоставить события из больших двоичных объектов, создаваемых в определенной подпапке контейнера, используйте subjectBeginsWith фильтр, например:

/blobServices/default/containers/{containername}/blobs/{subfolder}/

Чтобы сопоставить события из больших двоичных объектов, созданных в конкретном контейнере с общим суффиксом имени большого двоичного объекта, используйте фильтр subjectEndsWith, такой как ".log" или ".jpg".

Расширенная фильтрация

Вариант расширенной фильтрации позволяет выполнять фильтрацию по значениям в полях данных и указывать оператор сравнения. При расширенной фильтрации можно указать следующее:

operatorType — тип сравнения;
ключ — поле в данных события, которое используется для фильтрации Это может быть число, логическое значение, строка или массив.
Значения — значение или значения для сравнения с ключом.

Ключ.

Ключ — поле в данных события, которое используется для фильтрации. Может иметь один из следующих типов:

Число
Логический
Строка
Массива. Чтобы использовать эту функцию, необходимо присвоить свойству enableAdvancedFilteringOnArrays значение true.
```
"filter":
{
    "subjectBeginsWith": "/blobServices/default/containers/mycontainer/blobs/log",
    "subjectEndsWith": ".jpg",
    "enableAdvancedFilteringOnArrays": true
}
```

Для событий в схеме "События в облаке" используются следующие значения для ключа:eventid, source, eventtype, eventtypeversion или данные события (например, data.key1).

Если вы используете базовый уровень сетки событий, для событий в схеме сетки событий используйте следующие значения для ключа: ID, , Topic, EventTypeDataVersionSubjectили данных событий (напримерdata.key1). Для пользовательских схем ввода используются поля данных событий (например, data.key1). Чтобы получить доступ к полям в разделе data, используйте нотацию . (с точкой). Например, 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"
	},

Примечание.

Сетка событий не поддерживает фильтрацию по массиву объектов. Он разрешает только string, boolean, numbers и Array одинаковых типов (например, целочисленный массив или массив строк).

Values

Возможны следующие значения: число, строка, логическое значение или массив.

Операторы

Доступны следующие операторы для чисел:

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

NumberGreaterThanOrEquals;

Оператор 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]]
}

Массив с одним диапазоном:

{
    "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, если значение ключа является указанным логическим значением фильтра. В следующем примере проверяется, равно ли true значение атрибута isEnabled в разделе data.

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