Filtros de eventos para suscripciones a temas de espacio de nombres de Azure Event Grid

En este artículo se describen diferentes formas de especificar filtros en suscripciones de eventos a temas de espacio de nombres. Los filtros permiten enviar solo un subconjunto de eventos que el publicador envía a Event Grid al punto de conexión de destino. Al crear una suscripción de eventos, tiene tres opciones para filtrar:

• Tipos de eventos
• El asunto comienza con o termina con
• Campos y operadores avanzados

Filtrado de tipos de evento

De forma predeterminada, todos los tipos de eventos para el origen del evento 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 los recursos, pero no recibir notificaciones para otras operaciones como eliminaciones. En ese caso, filtre por el tipo de Microsoft.Resources.ResourceWriteSuccess evento. Proporcione una matriz con los tipos de evento o especifique All para obtener todos los tipos de eventos para el origen del evento.

La sintaxis JSON para filtrar por tipo de evento es:

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

Filtrado de asunto

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

Al publicar eventos en temas personalizados, cree temas para los eventos que facilitan a los suscriptores saber si están interesados en el evento. Los suscriptores usan la propiedad subject para filtrar y enrutar eventos. Considere la posibilidad de agregar la ruta de acceso para dónde se produjo el evento, por lo que los suscriptores pueden filtrar por segmentos de esa ruta de acceso. La ruta de acceso permite a los suscriptores filtrar eventos de forma estrecha o amplia. 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 temas como /A/B/C o /A/D/E. Otros suscriptores pueden filtrar por /A/B para obtener un conjunto más estrecho de eventos.

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 usa el formato :

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

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

Para hacer coincidir eventos de blobs creados en un conjunto de contenedores que comparten un prefijo, use un subjectBeginsWith filtro como:

/blobServices/default/containers/containerprefix

Para buscar coincidencias con eventos de blobs creados en un contenedor específico, use un subjectBeginsWith filtro como:

/blobServices/default/containers/containername/

Para hacer coincidir eventos de blobs creados en contenedores específicos que comparten un prefijo de nombre de blob, use un subjectBeginsWith filtro como:

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

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

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

Para hacer coincidir eventos de blobs creados en contenedores específicos que comparten un sufijo de blob, use un subjectEndsWith filtro 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 avanzado. En el filtrado avanzado, especifique lo siguiente:

• tipo de operador: tipo de comparación.
• key: el campo de los datos de evento que está usando para el filtrado. Puede ser un número, un valor booleano, una cadena o una matriz.
• values: valor o valores que se van a comparar con la clave.

Key

La clave es el campo de los datos de evento que se usan para el filtrado. Puede ser uno de los siguientes tipos:

• Number

• Boolean

• String

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

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

Para eventos en el esquema de Eventos en la nube, use los siguientes valores para la clave: eventid, source, eventtype, eventtypeversiono datos de eventos (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, DataVersiono datos de eventos (como data.key1). Para el esquema de entrada personalizado, use los campos de datos del evento (como data.key1). Para acceder a los campos de la sección de datos, use la . notación (dot). Por ejemplo, , data.siteNamedata.appEventTypeDetail.action para acceder siteName a 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"
	},

Valores

Los valores pueden ser: number, string, boolean o array.

Operadores

Los operadores disponibles para los números son:

NumberIn

El operador NumberIn se evalúa como true si el valor de clave es uno de los valores de filtro especificados. En el ejemplo siguiente, comprueba si el valor del counter atributo de la data sección 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 omiten.

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

NumberNotIn

NumberNotIn se evalúa como true si el valor de claveno es ninguno de los valores de filtro especificados. En el ejemplo siguiente, comprueba si el valor del counter atributo de la data sección no es 41 y 0.

"advancedFilters": [{
    "operatorType": "NumberNotIn",
    "key": "data.counter",
    "values": [
        41,
        0
    ]
}]

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 omiten.

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 como true si el valor de clave es menor que el valor de filtro especificado. En el ejemplo siguiente, comprueba si el valor del counter atributo de la data sección es inferior a 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 omiten.

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

NumberGreaterThan

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

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

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 omiten.

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

NumberLessThanOrEquals

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

"advancedFilters": [{
    "operatorType": "NumberLessThanOrEquals",
    "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 omiten.

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

NumberGreaterThanOrEquals

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

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

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 omiten.

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

NumberInRange

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

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

La values propiedad 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 que se va a 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 el filtro: una matriz de intervalos. En este pseudocódigo, a y b son valores bajos y altos 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 omiten.

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 como true si el valor de claveno está en ninguno de los intervalos de filtros especificados. En el ejemplo siguiente, comprueba si el valor del key1 atributo de la data sección está en 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 values propiedad 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 que se va a comprobar.

Matriz con un intervalo:

{
    "operatorType": "NumberNotInRange",
    "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 el filtro: una matriz de intervalos. En este pseudocódigo, a y b son valores bajos y altos 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 omiten.

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 booleanos es:

BoolEquals

El operador BoolEquals se evalúa como true si el valor de clave es el filtro de valor booleano especificado. En el ejemplo siguiente, comprueba si el valor del isEnabled atributo de la data sección 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 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 omiten.

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

Los operadores disponibles para las cadenas son:

StringContains

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

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

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 omiten.

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

StringNotContains

El operador StringNotContains se evalúa como true si la claveno contiene los valores de filtro especificados como subcadenas. Si la clave contiene uno de los valores especificados como subcadena, el operador se evalúa como false. En el ejemplo siguiente, el operador devuelve true solo si el valor del key1 atributo de la data sección no tiene contoso y fabrikam como subcadenas.

"advancedFilters": [{
    "operatorType": "StringNotContains",
    "key": "data.key1",
    "values": [
        "contoso", 
        "fabrikam"
    ]
}]

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 omiten.

FOR_EACH filter IN (a, b, c)
    FOR_EACH key IN (v1, v2, v3)
        IF key CONTAINS filter
            FAIL_MATCH

Consulte la sección Limitaciones para ver la limitación actual de este operador.

StringBeginsWith

El operador StringBeginsWith se evalúa como true si el valor de clave comienza con cualquiera de los valores de filtroespecificados. En el ejemplo siguiente, comprueba si el valor del key1 atributo de la data sección comienza por event o message. Por ejemplo, event hubs comienza con event.

"advancedFilters": [{
    "operatorType": "StringBeginsWith",
    "key": "data.key1",
    "values": [
        "event", 
        "message"
    ]
}]

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 omiten.

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

StringNotBeginsWith

El operador StringNotBeginsWith se evalúa como true si el valor de claveno comienza con ninguno de los valores de filtro especificados. En el ejemplo siguiente, comprueba si el valor del key1 atributo de la data sección no comienza por event o message.

"advancedFilters": [{
    "operatorType": "StringNotBeginsWith",
    "key": "data.key1",
    "values": [
        "event", 
        "message"
    ]
}]

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 omiten.

FOR_EACH filter IN (a, b, c)
    FOR_EACH key IN (v1, v2, v3)
        IF key BEGINS_WITH filter
            FAIL_MATCH

StringEndsWith

El operador StringEndsWith se evalúa como true si el valor de clavetermina con uno de los valores de filtro especificados. En el ejemplo siguiente, comprueba si el valor del key1 atributo de la data sección termina con jpg o jpegpng. Por ejemplo, eventgrid.png termina con png.

"advancedFilters": [{
    "operatorType": "StringEndsWith",
    "key": "data.key1",
    "values": [
        "jpg", 
        "jpeg", 
        "png"
    ]
}]

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 omiten.

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

StringNotEndsWith

El operador StringNotEndsWith se evalúa como true si el valor de claveno termina con ninguno de los valores de filtro especificados. En el ejemplo siguiente, comprueba si el valor del key1 atributo de la data sección no termina con jpg o jpegpng.

"advancedFilters": [{
    "operatorType": "StringNotEndsWith",
    "key": "data.key1",
    "values": [
        "jpg", 
        "jpeg", 
        "png"
    ]
}]

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 omiten.

FOR_EACH filter IN (a, b, c)
    FOR_EACH key IN (v1, v2, v3)
        IF key ENDS_WITH filter
            FAIL_MATCH

StringIn

El operador StringIn comprueba si el valor de clavecoincide exactamente con uno de los valores de filtro especificados. En el ejemplo siguiente, comprueba si el valor del key1 atributo de la data sección es contoso o fabrikamfactory.

"advancedFilters": [{
    "operatorType": "StringIn",
    "key": "data.key1",
    "values": [
        "contoso", 
        "fabrikam", 
        "factory"
    ]
}]

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 omiten.

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

StringNotIn

El operador StringNotIn comprueba si el valor de claveno coincide con ninguno de los valores de filtro especificados. En el ejemplo siguiente, comprueba si el valor del key1 atributo de la data sección no aws es y bridge.

"advancedFilters": [{
    "operatorType": "StringNotIn",
    "key": "data.key1",
    "values": [
        "aws", 
        "bridge"
    ]
}]

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 omiten.

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

Todas las comparaciones de cadenas no distinguen mayúsculas de minúsculas.

IsNullOrUndefined

El operador IsNullOrUndefined se evalúa como true si el valor de la clave es NULL o no definido.

{
    "operatorType": "IsNullOrUndefined",
    "key": "data.key1"
}

En el ejemplo siguiente, falta key1, por lo que el operador se evaluaría como true.

{ 
    "data": 
    { 
        "key2": 5 
    } 
}

En el ejemplo siguiente, key1 se establece en NULL, por lo que el operador se evaluaría como true.

{
    "data": 
    { 
        "key1": null
    }
}

Si key1 tiene cualquier otro valor en estos ejemplos, el operador se evaluaría como false.

IsNotNull

El operador IsNotNull se evalúa como true si el valor de la clave no es NULL o no está definido.

{
    "operatorType": "IsNotNull",
    "key": "data.key1"
}

OR and AND

Si especifica un único filtro con varios valores, se realiza una operación OR , por lo que el valor del campo de clave debe ser uno de estos valores. Este es un ejemplo:

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

Si especifica varios filtros diferentes, se realiza una operación AND , por lo que se debe cumplir cada condición de filtro. Este es un ejemplo:

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

CloudEvents

Para los eventos del esquema CloudEvents, use los siguientes valores para la clave: id, source, type, dataschemao datos de eventos (como data.key1).

También puede usar atributos de contexto de extensión en CloudEvents 1.0. En el ejemplo siguiente, comexampleextension1 y comexampleothervalue son atributos de contexto de extensión.

{
    "specversion" : "1.0",
    "type" : "com.example.someevent",
    "source" : "/mycontext",
    "id" : "C234-1234-1234",
    "time" : "2018-04-05T17:31:00Z",
    "subject": null,
    "comexampleextension1" : "value",
    "comexampleothervalue" : 5,
    "datacontenttype" : "application/json",
    "data" : {
        "appinfoA" : "abc",
        "appinfoB" : 123,
        "appinfoC" : true
    }
}

Este es un ejemplo del uso de un atributo de contexto de extensión en un filtro.

"advancedFilters": [{
    "operatorType": "StringBeginsWith",
    "key": "comexampleothervalue",
    "values": [
        "5", 
        "1"
    ]
}]

Limitaciones

El filtrado avanzado tiene las siguientes limitaciones:

• 25 filtros avanzados y 25 valores de filtro en todos los filtros por suscripción de Event Grid
• 512 caracteres por valor de cadena
• Teclas con . carácter (punto) en ellos. Por ejemplo: http://schemas.microsoft.com/claims/authnclassreference o john.doe@contoso.com. Actualmente, no hay compatibilidad con caracteres de escape en las claves.

La misma clave se puede usar en más de un filtro.

Pasos siguientes

• Creación, visualización y administración de espacios de nombres
• Inicio rápido: Publicación y suscripción a eventos de aplicación mediante temas de espacio de nombres
• SDK del plano de control y del plano de datos
• Cuotas y límites