Descripción del filtrado de eventos para suscripciones de Event Grid

Artículo
12/12/2024

En este artículo se describen las distintas formas de filtrar los eventos que se envían al punto de conexión. Al crear una suscripción de eventos, se le presentan tres opciones de filtrado:

Tipos de eventos
El asunto empieza o termina con
Operadores y campos avanzados

Plantilla del Administrador de recursos de Azure

Los ejemplos que se muestran en este artículo son fragmentos de código JSON para definir filtros en plantillas de Azure Resource Manager (ARM). Para obtener un ejemplo de una plantilla de ARM completa e implementarla, consulte Inicio rápido: Enrutamiento de eventos de Blob Storage al punto de conexión web mediante una plantilla de ARM. Estas son algunas secciones más sobre la sección filter del ejemplo del inicio rápido. La plantilla de ARM define los recursos siguientes.

Cuenta de almacenamiento de Azure
Tema del sistema para la cuenta de almacenamiento
Suscripción de eventos para el tema del sistema. Consulte la subsección filter en la sección suscripción de eventos.

En el ejemplo siguiente, la suscripción de eventos filtra los eventos Microsoft.Storage.BlobCreated y 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'))]"
      ]
    }
  ]
}

Filtrado de tipos de evento

De forma predeterminada, todos los tipos de evento del origen de eventos se envían al punto de conexión. Puede decidir enviar solo determinados tipos de eventos al punto de conexión. Por ejemplo, puede recibir una notificación de las actualizaciones de sus recursos pero no de otras operaciones, como las eliminaciones. En ese caso, filtre por el tipo de evento Microsoft.Resources.ResourceWriteSuccess. Proporcione una matriz con los tipos de eventos, o especifique All para obtener todos los tipos de evento para el origen del evento.

La sintaxis JSON para el filtrado por tipo de evento es:

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

Filtrado de asunto

Para filtrar solo por asunto, especifique un valor inicial o final para el asunto. Por ejemplo, puede especificar que el asunto termina con .txt para obtener solo los eventos relacionados con la carga de un archivo de texto a la cuenta de almacenamiento. O bien, puede filtrar que el sujeto empieza por /blobServices/default/containers/testcontainer para obtener todos los eventos de ese contenedor, pero no otros contenedores en la cuenta de almacenamiento.

Al publicar eventos en temas personalizados, cree asuntos para los eventos que faciliten que los suscriptores sepan si les interesa el evento. Los suscriptores usan la propiedad del asunto para filtrar y redirigir eventos. Considere la posibilidad de agregar la ruta de acceso de donde se produjo el evento, para que los suscriptores pueden filtrar por los segmentos de esa ruta de acceso. La ruta de acceso permite que los suscriptores filtren eventos de una manera más amplia o más restringida. Si proporciona una ruta de acceso de tres segmentos como /A/B/C en el asunto, los suscriptores pueden filtrar por el primer segmento /A para obtener un amplio conjunto de eventos. Esos suscriptores obtienen eventos con asuntos como /A/B/C o /A/D/E. Otros suscriptores pueden filtrar por /A/B para obtener un conjunto de eventos más reducido.

Ejemplos (eventos de Blob Storage)

Los eventos de blob se pueden filtrar por el tipo de evento, el nombre del contenedor o el nombre del objeto que se creó o eliminó.

El asunto de los eventos de Blob Storage utiliza el formato:

/blobServices/default/containers/<containername>/blobs/<blobname>

Para que coincida con todos los eventos de una cuenta de almacenamiento, los filtros de asunto se pueden dejar vacíos.

Para que coincida con eventos de blobs creados en un conjunto de contenedores que comparten un prefijo, utilice un filtro subjectBeginsWith como:

/blobServices/default/containers/containerprefix

Para que coincida con eventos de blobs creados en un contenedor concreto, utilice un filtro subjectBeginsWith como:

/blobServices/default/containers/containername/

Para que coincida con eventos de blobs creados en un contenedor concreto que comparten un prefijo de nombre de blob, utilice un filtro subjectBeginsWith como:

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

Para hacer coincidir eventos de blobs creados en una subcarpeta específica de un contenedor, use un filtro de subjectBeginsWith como:

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

Para que coincida con eventos de blobs creados en un contenedor concreto que comparten un sufijo de blob, utilice un filtro subjectEndsWith como ".log" o ".jpg".

Filtrado avanzado

Para filtrar por valores en los campos de datos y especificar el operador de comparación, use la opción de filtrado avanzada. En el filtrado avanzado, se especifica lo siguiente:

tipo de operador: el tipo de comparación.
clave: el campo de datos de evento que se usa para filtrar. Puede ser un número, un valor booleano, una cadena o una matriz.
valores: el valor o los valores que se compararán con la clave.

Clave

Clave es el campo de datos de evento que se usa para filtrar. Puede ser uno de los siguientes tipos:

Number
Boolean
String

Matriz. Debe establecer la propiedad enableAdvancedFilteringOnArrays en true para usar esta característica.

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

Para los eventos del esquema de Cloud Events, utilice los valores siguientes para la clave: eventid, source, eventtype, eventtypeversion o datos de evento (como data.key1).

Si usa el nivel básico de Event Grid, para eventos en el esquema de Event Grid, use los siguientes valores para la clave:ID, Topic, Subject, EventType, DataVersion o datos de eventos (como data.key1). Para el esquema de entrada personalizado, use los campos de datos de evento (como data.key1). Para acceder a los campos de la sección de datos, use la notación . (punto). Por ejemplo, data.siteName, data.appEventTypeDetail.action para acceder a siteName o action para el siguiente evento de ejemplo.

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

Nota:

Event Grid no admite el filtrado en una matriz de objetos. Solo permite cadenas, booleanos, números y matrices del mismo tipo (como matrices de enteros o matrices de cadenas).

Valores

Los valores pueden ser: número, cadena, booleano o matriz.

Operadores

Los operadores disponibles para los números son:

NumberIn

El operador NumberIn se evalúa en true si el valor de la clave es uno de los valores de filtro especificados. En el ejemplo siguiente, comprueba si el valor del atributo counter de la sección data es 5 o 1.

"advancedFilters": [{
    "operatorType": "NumberIn",
    "key": "data.counter",
    "values": [
        5,
        1
    ]
}]

Si la clave es una matriz, todos los valores de la matriz se comprueban con la matriz de valores de filtro. Este es el pseudocódigo con la clave [v1, v2, v3] y el filtro [a, b, c]. Los valores de clave con tipos de datos que no coinciden con el tipo de datos del filtro se ignoran.

FOR_EACH filter IN (a, b, c)
    FOR_EACH key IN (v1, v2, v3)
        IF filter == key
            MATCH

NumberNotIn

El operador NumberNotIn se evalúa en true si el valor de la claveno es ninguno de los valores de filtro especificados. En el ejemplo siguiente, comprueba si el valor del atributo counter de la sección data no es 41 y 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

El operador NumberLessThan se evalúa en true si el valor de la clave es menor que el valor de filtro especificado. En el ejemplo siguiente, comprueba si el valor del atributo counter de la sección data es menor que 100.

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

Si la clave es una matriz, todos los valores de la matriz se comprueban con el valor de filtro. Este es el pseudocódigo con la clave: [v1, v2, v3]. Los valores de clave con tipos de datos que no coinciden con el tipo de datos del filtro se ignoran.

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

NumberGreaterThan

El operador NumberGreaterThan se evalúa en true si el valor de la clave es mayor que el valor de filtro especificado. En el ejemplo siguiente, comprueba si el valor del atributo counter de la sección data es mayor que 20.

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

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

NumberLessThanOrEquals

El operador NumberLessThanOrEquals se evalúa en true si el valor de la clave es menor o igual que el valor de filtro especificado. En el ejemplo siguiente, comprueba si el valor del atributo counter de la sección data es menor o igual que 100.

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

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

NumberGreaterThanOrEquals

El operador NumberGreaterThanOrEquals se evalúa en true si el valor de la clave es mayor o igual que el valor de filtro especificado. En el ejemplo siguiente, comprueba si el valor del atributo counter de la sección data es mayor o igual que 30.

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

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

NumberInRange

El operador NumberInRange se evalúa en true si el valor de la clave es uno de los intervalos de filtros especificados. En el ejemplo siguiente, comprueba si el valor del atributo key1 de la sección data se encuentra dentro de uno de los dos intervalos: 3.14159 - 999.95, 3000 - 4000.

{
    "operatorType": "NumberInRange",
    "key": "data.key1",
    "values": [[3.14159, 999.95], [3000, 4000]]
}

La propiedad values es una matriz de intervalos. En el ejemplo anterior, es una matriz de dos intervalos. Este es un ejemplo de una matriz con un intervalo para comprobar.

Matriz con un intervalo:

{
    "operatorType": "NumberInRange",
    "key": "data.key1",
    "values": [[3000, 4000]]
}

Si la clave es una matriz, todos los valores de la matriz se comprueban con la matriz de valores de filtro. Este es el pseudocódigo con la clave [v1, v2, v3] y una matriz de intervalos como filtro. En este pseudocódigo, a y b son los valores inferior y superior de cada intervalo de la matriz. Los valores de clave con tipos de datos que no coinciden con el tipo de datos del filtro se ignoran.

FOR_EACH (a,b) IN filter.Values
    FOR_EACH key IN (v1, v2, v3)
       IF key >= a AND key <= b
           MATCH

NumberNotInRange

El operador NumberNotInRange se evalúa en true si el valor de la claveno se encuentra dentro de ninguno de los intervalos de filtros especificados. En el ejemplo siguiente, comprueba si el valor del atributo key1 de la sección data se encuentra dentro de uno de los dos intervalos: 3.14159 - 999.95, 3000 - 4000. Si es así, el operador devuelve false.

{
    "operatorType": "NumberNotInRange",
    "key": "data.key1",
    "values": [[3.14159, 999.95], [3000, 4000]]
}

La propiedad values es una matriz de intervalos. En el ejemplo anterior, es una matriz de dos intervalos. Este es un ejemplo de una matriz con un intervalo para comprobar.

Matriz con un intervalo:

{
    "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

El operador disponible para los booleanos es:

BoolEquals

El operador BoolEquals se evalúa en true si el valor de la clave es el filtro del valor booleano especificado. En el ejemplo siguiente, comprueba si el valor del atributo isEnabled de la sección data es true.

"advancedFilters": [{
    "operatorType": "BoolEquals",
    "key": "data.isEnabled",
    "value": true
}]

Si la clave es una matriz, todos los valores de la matriz se comprueban con el valor booleano del filtro. Este es el pseudocódigo con la clave: [v1, v2, v3]. Los valores de clave con tipos de datos que no coinciden con el tipo de datos del filtro se ignoran.

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

Los operadores disponibles para las cadenas son:

StringContains

El operador StringContains se evalúa en true si el valor de la clavecontiene cualquiera de los valores de filtro especificados (como subcadenas). En el ejemplo siguiente, comprueba si el valor del atributo key1 de la sección data contiene una de las subcadenas especificadas: microsoft o azure. Por ejemplo, azure data factory contiene azure.

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