Compreender a filtragem de eventos para subscrições da Grelha de Eventos

Artigo
12/14/2024

Este artigo descreve as diferentes maneiras de filtrar quais eventos são enviados para seu ponto de extremidade. Ao criar uma assinatura de evento, você tem três opções de filtragem:

Tipos de evento
O assunto começa com ou termina com
Campos avançados e operadores

Modelo Azure Resource Manager

Os exemplos mostrados neste artigo são trechos JSON para definir filtros em modelos do Azure Resource Manager (ARM). Para obter um exemplo de um modelo ARM completo e implantação de um modelo ARM, consulte Guia de início rápido: rotear eventos de armazenamento de Blob para o ponto de extremidade da Web usando um modelo ARM. Aqui estão mais algumas seções ao redor da filter seção do exemplo no início rápido. O modelo ARM define os seguintes recursos.

Conta de armazenamento do Azure
Tópico do sistema para a conta de armazenamento
Subscrição de eventos para o tópico do sistema. Consulte a filter subsecção na secção de subscrição de eventos.

No exemplo a seguir, a assinatura de evento filtra para Microsoft.Storage.BlobCreated e Microsoft.Storage.BlobDeleted eventos.

{
  "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'))]"
      ]
    }
  ]
}

Filtragem de tipo de evento

Por padrão, todos os tipos de evento para a fonte do evento são enviados para o ponto de extremidade. Você pode decidir enviar apenas determinados tipos de evento para seu ponto de extremidade. Por exemplo, você pode ser notificado sobre atualizações em seus recursos, mas não notificado sobre outras operações, como exclusões. Nesse caso, filtre pelo tipo de Microsoft.Resources.ResourceWriteSuccess evento. Forneça uma matriz com os tipos de evento ou especifique All para obter todos os tipos de evento para a fonte do evento.

A sintaxe JSON para filtragem por tipo de evento é:

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

Filtragem de assunto

Para filtragem simples por assunto, especifique um valor inicial ou final para o assunto. Por exemplo, você pode especificar que o assunto termina com .txt para obter apenas eventos relacionados ao upload de um arquivo de texto para a conta de armazenamento. Ou, você pode filtrar o assunto começa com /blobServices/default/containers/testcontainer para obter todos os eventos para esse contêiner, mas não outros contêineres na conta de armazenamento.

Ao publicar eventos em tópicos personalizados, crie assuntos para os seus eventos que facilitem aos subscritores saber se estão interessados no evento. Os assinantes usam a propriedade subject para filtrar e rotear eventos. Considere adicionar o caminho para onde o evento aconteceu, para que os assinantes possam filtrar por segmentos desse caminho. O caminho permite que os assinantes filtrem eventos de forma restrita ou ampla. Se você fornecer um caminho de três segmentos, como /A/B/C no assunto, os assinantes poderão filtrar pelo primeiro segmento /A para obter um amplo conjunto de eventos. Esses assinantes recebem eventos com assuntos como /A/B/C ou /A/D/E. Outros subscritores podem filtrar para /A/B obter um conjunto mais restrito de eventos.

Exemplos (eventos de armazenamento de Blob)

Os eventos de Blob podem ser filtrados pelo tipo de evento, nome do contêiner ou nome do objeto que foi criado ou excluído.

O assunto dos eventos de armazenamento de Blob usa o formato:

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

Para fazer corresponder todos os eventos de uma conta de armazenamento, você pode deixar os filtros de assunto vazios.

Para corresponder a eventos de blobs criados em um conjunto de contêineres que compartilham um prefixo, use um subjectBeginsWith filtro como:

/blobServices/default/containers/containerprefix

Para corresponder a eventos de blobs criados em contêiner específico, use um subjectBeginsWith filtro como:

/blobServices/default/containers/containername/

Para corresponder a eventos de blobs criados em contêineres específicos que compartilham um prefixo de nome de blob, use um subjectBeginsWith filtro como:

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

Para corresponder a eventos de blobs criados em uma subpasta específica de um contêiner, use um subjectBeginsWith filtro como:

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

Para corresponder a eventos de blobs criados em contêineres específicos que compartilham um sufixo de blob, use um subjectEndsWith filtro como ".log" ou ".jpg".

Filtragem avançada

Para filtrar por valores nos campos de dados e especificar o operador de comparação, use a opção de filtragem avançada. Na filtragem avançada, você especifica:

tipo de operador - O tipo de comparação.
key - O campo nos dados do evento que você está usando para filtragem. Pode ser um número, booleano, cadeia de caracteres ou uma matriz.
values - O valor ou valores a comparar com a chave.

Chave

Chave é o campo nos dados do evento que você está usando para filtragem. Pode ser um dos seguintes tipos:

Número
Booleano
String

Matriz. Você precisa definir a enableAdvancedFilteringOnArrays propriedade como true para usar esse recurso.

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

Para eventos no esquema Cloud Events, use os seguintes valores para a chave: eventid, source, eventtype, eventtypeversion, ou dados de evento (como data.key1).

Se você estiver usando a camada básica da Grade de Eventos, para eventos no esquema de Grade de Eventos, use os seguintes valores para a chave: ID, Topic, Subject, EventType, DataVersionou dados de evento (como data.key1). Para esquema de entrada personalizado, use os campos de dados de evento (como data.key1). Para acessar campos na seção de dados, use a . notação (ponto). Por exemplo, data.siteNamepara data.appEventTypeDetail.action acessar siteName ou action para o seguinte evento de exemplo.

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

Nota

A Grade de Eventos não oferece suporte à filtragem em uma matriz de objetos. Ele só permite String, Boolean, Numbers e Array dos mesmos tipos (como matriz inteira ou matriz de string).

Valores

Os valores podem ser: número, string, booleano ou array

Operadores

Os operadores disponíveis para os números são:

NúmeroIn

O operador NumberIn avalia como true se o valor da chave for um dos valores de filtro especificados. No exemplo a seguir, ele verifica se o counter valor do atributo na data seção é 5 ou 1.

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

Se a chave for uma matriz, todos os valores na matriz serão verificados em relação à matriz de valores de filtro. Aqui está o pseudo código com a chave: [v1, v2, v3] e o filtro: [a, b, c]. Todos os valores-chave com tipos de dados que não correspondem ao tipo de dados do filtro são ignorados.

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

NúmeroNotIn

O NumberNotIn é avaliado como true se o valor da chave não for qualquer um dos valores de filtro especificados. No exemplo a seguir, ele verifica se o counter valor do atributo na data seção não é 41 e 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

NúmeroLessThan

O operador NumberLessThan avalia como true se o valor da chave for menor que o valor do filtro especificado. No exemplo a seguir, ele verifica se o counter valor do atributo na data seção é menor que 100.

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

Se a chave for uma matriz, todos os valores na matriz serão verificados em relação ao valor do filtro. Aqui está o pseudo código com a chave: [v1, v2, v3]. Todos os valores-chave com tipos de dados que não correspondem ao tipo de dados do filtro são ignorados.

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

NúmeroMaiorQue

O operador NumberGreaterThan avalia como true se o valor da chave for maior do que o valor do filtro especificado. No exemplo a seguir, ele verifica se o counter valor do atributo na data seção é maior que 20.

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

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

NumberLessThanOrEquals

O operador NumberLessThanOrEquals avalia como true se o valor da chave for menor ou igual ao valor do filtro especificado. No exemplo a seguir, ele verifica se o counter valor do atributo na data seção é menor ou igual a 100.

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

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

NumberGreaterThanOrEquals

O operador NumberGreaterThanOrEquals avalia como true se o valor da chave for maior ou igual ao valor do filtro especificado. No exemplo a seguir, ele verifica se o counter valor do atributo na data seção é maior ou igual a 30.

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

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

NumberInRange

O operador NumberInRange avalia como true se o valor da chave estiver em um dos intervalos de filtros especificados. No exemplo a seguir, ele verifica se o key1 valor do atributo na data seção está em um dos dois intervalos: 3.14159 - 999.95, 3000 - 4000.

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

A values propriedade é uma matriz de intervalos. No exemplo anterior, é uma matriz de dois intervalos. Aqui está um exemplo de uma matriz com um intervalo para verificar.

Matriz com um intervalo:

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

Se a chave for uma matriz, todos os valores na matriz serão verificados em relação à matriz de valores de filtro. Aqui está o pseudo código com a chave: [v1, v2, v3] e o filtro: uma matriz de intervalos. Neste pseudo código, a e b são valores baixos e altos de cada intervalo na matriz. Todos os valores-chave com tipos de dados que não correspondem ao tipo de dados do filtro são ignorados.

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

NúmeroNotInRange

O operador NumberNotInRange avalia como true se o valor da chave não estiver em nenhum dos intervalos de filtros especificados. No exemplo a seguir, ele verifica se o key1 valor do atributo na data seção está em um dos dois intervalos: 3.14159 - 999.95, 3000 - 4000. Se for, o operador retorna false.

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

A values propriedade é uma matriz de intervalos. No exemplo anterior, é uma matriz de dois intervalos. Aqui está um exemplo de uma matriz com um intervalo para verificar.

Matriz com um 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

O operador disponível para booleanos é:

BoolEquals

O operador BoolEquals avalia como true se o valor da chave for o filtro de valor booleano especificado. No exemplo a seguir, ele verifica se o isEnabled valor do atributo na data seção é true.

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

Se a chave for uma matriz, todos os valores na matriz serão verificados em relação ao valor booleano do filtro. Aqui está o pseudo código com a chave: [v1, v2, v3]. Todos os valores-chave com tipos de dados que não correspondem ao tipo de dados do filtro são ignorados.

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

Os operadores disponíveis para strings são:

StringContains

O StringContains avalia como true se o valor da chave contém qualquer um dos valores de filtro especificados (como substrings). No exemplo a seguir, ele verifica se o key1 valor do atributo na data seção contém uma das substrings especificadas: microsoft ou azure. Por exemplo, azure data factory tem azure nele.

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