Filtrar eventos para a Grelha de Eventos

Este artigo mostra-lhe como filtrar os eventos que o Event Grid entrega ao seu endpoint quando cria uma subscrição de evento. Pode filtrar por tipo de evento, por assunto, ou por campos e operadores avançados, para que apenas os eventos que lhe interessam cheguem ao seu handler.

Os exemplos utilizam modelos do Azure PowerShell, do CLI do Azure, do portal do Azure e do Azure Resource Manager (ARM). Usa a ferramenta que se adequar ao teu fluxo de trabalho. Para conhecer melhor as opções de filtragem disponíveis, consulte Compreender a filtragem de eventos para subscrições do Event Grid.

Pré-requisitos

• Uma assinatura ativa do Azure. Se não tiver uma, crie uma conta gratuita antes de começar.
• Azure PowerShell ou CLI do Azure instalados, se planeias correr os exemplos do PowerShell ou CLI. Para mais informações, consulte Instalar o módulo PowerShell do Azure Az ou Como instalar o CLI do Azure.
• Um tema existente da Grade de Eventos ou tópico do sistema, e um endpoint para receber os eventos filtrados. Alguns exemplos geram automaticamente o tópico necessário.

Filtrar por tipo de evento

Ao criar uma subscrição do Event Grid, pode especificar que tipos de evento pretende enviar para o ponto final. Os exemplos seguintes criam subscrições de eventos para um grupo de recursos, mas limitam os eventos enviados para Microsoft.Resources.ResourceWriteFailure e Microsoft.Resources.ResourceWriteSuccess. Se precisar de mais flexibilidade ao filtrar eventos por tipos de evento, consulte Filtrar por operadores e dados.

Azure PowerShell

Para o PowerShell, use o -IncludedEventType parâmetro ao criar a assinatura.

$includedEventTypes = "Microsoft.Resources.ResourceWriteFailure", "Microsoft.Resources.ResourceWriteSuccess"

New-AzEventGridSubscription `
  -EventSubscriptionName demoSubToResourceGroup `
  -ResourceGroupName myResourceGroup `
  -Endpoint <endpoint-URL> `
  -IncludedEventType $includedEventTypes

CLI do Azure

Para a CLI do Azure, use o --included-event-types parâmetro. O exemplo a seguir usa a CLI do Azure em um shell Bash:

includedEventTypes="Microsoft.Resources.ResourceWriteFailure Microsoft.Resources.ResourceWriteSuccess"

az eventgrid event-subscription create \
  --name demoSubToResourceGroup \
  --resource-group myResourceGroup \
  --endpoint <endpoint-URL> \
  --included-event-types $includedEventTypes

portal do Azure

Ao criar uma assinatura de evento para um tópico do sistema, use a lista suspensa para selecionar os tipos de evento, conforme mostrado na imagem a seguir.

Para uma subscrição existente de um tópico de sistema, utilize o separador Filtros da página Subscrição de Evento, conforme mostrado na imagem seguinte.

Especifique filtros ao criar um tópico personalizado selecionando o link Adicionar Tipo de Evento , conforme mostrado na imagem seguinte.

Para especificar um filtro para uma subscrição existente de um tópico personalizado, utilize o separador Filtros na página Subscrição de Evento.

Modelo Azure Resource Manager

Para um modelo do Gestor de Recursos, use a propriedade includedEventTypes.

"resources": [
  {
    "type": "Microsoft.EventGrid/eventSubscriptions",
    "name": "[parameters('eventSubName')]",
    "apiVersion": "2025-02-15",
    "properties": {
      "destination": {
        "endpointType": "WebHook",
        "properties": {
          "endpointUrl": "[parameters('endpoint')]"
        }
      },
      "filter": {
        "subjectBeginsWith": "",
        "subjectEndsWith": "",
        "isSubjectCaseSensitive": false,
        "includedEventTypes": [
          "Microsoft.Resources.ResourceWriteFailure",
          "Microsoft.Resources.ResourceWriteSuccess"
        ]
      }
    }
  }
]

Filtrar por assunto

Você pode filtrar eventos pelo assunto nos dados do evento. Pode especificar um valor para corresponder ao início ou ao fim do assunto. Se precisar de mais flexibilidade ao filtrar eventos por assunto, consulte Filtrar por operadores e dados.

No exemplo do PowerShell a seguir, você cria uma assinatura de evento que filtra pelo início do assunto. Utiliza o parâmetro -SubjectBeginsWith para limitar os eventos aos de um recurso específico. Você passa a ID de recurso de um grupo de segurança de rede.

Azure PowerShell

$resourceId = (Get-AzResource -ResourceName demoSecurityGroup -ResourceGroupName myResourceGroup).ResourceId

New-AzEventGridSubscription `
  -Endpoint <endpoint-URL> `
  -EventSubscriptionName demoSubscriptionToResourceGroup `
  -ResourceGroupName myResourceGroup `
  -SubjectBeginsWith $resourceId

O próximo exemplo do PowerShell cria uma assinatura para um armazenamento de blob. Limita os eventos àqueles com um assunto que termina em .jpg.

$storageId = (Get-AzStorageAccount -ResourceGroupName myResourceGroup -AccountName $storageName).Id

New-AzEventGridSubscription `
  -EventSubscriptionName demoSubToStorage `
  -Endpoint <endpoint-URL> `
  -ResourceId $storageId `
  -SubjectEndsWith ".jpg"

CLI do Azure

No exemplo da CLI do Azure a seguir, você cria uma assinatura de evento que filtra pelo início do assunto. Utiliza o parâmetro --subject-begins-with para limitar os eventos aos de um recurso específico. Você passa a ID de recurso de um grupo de segurança de rede.

resourceId=$(az network nsg show -g myResourceGroup -n demoSecurityGroup --query id --output tsv)

az eventgrid event-subscription create \
  --name demoSubscriptionToResourceGroup \
  --resource-group myResourceGroup \
  --endpoint <endpoint-URL> \
  --subject-begins-with $resourceId

O próximo exemplo da CLI do Azure cria uma assinatura para um armazenamento de blob. Limita os eventos àqueles com um assunto que termina em .jpg.

storageid=$(az storage account show --name $storageName --resource-group myResourceGroup --query id --output tsv)

az eventgrid event-subscription create \
  --resource-id $storageid \
  --name demoSubToStorage \
  --endpoint <endpoint-URL> \
  --subject-ends-with ".jpg"

portal do Azure

Para uma subscrição de evento existente:

1. Na página Subscrição de Eventos , selecione Ativar filtragem de assuntos.

2. Insira valores para um ou mais dos seguintes campos: Assunto começa com e Assunto termina com. No exemplo a seguir, ambas as opções são selecionadas.

   

3. Selecione a opção Correspondência entre maiúsculas e minúsculas no assunto se quiser que o assunto do evento respeite a distinção entre maiúsculas e minúsculas dos filtros especificados.

Ao criar uma assinatura de evento, use o separador Filters do assistente de criação.

Modelo Azure Resource Manager

No exemplo de modelo do Gerenciador de Recursos a seguir, você cria uma assinatura de evento que filtra pelo início do assunto. Utilize a propriedade subjectBeginsWith para limitar os eventos aos de um recurso específico. Você passa a ID de recurso de um grupo de segurança de rede.

"resources": [
  {
    "type": "Microsoft.EventGrid/eventSubscriptions",
    "name": "[parameters('eventSubName')]",
    "apiVersion": "2025-02-15",
    "properties": {
      "destination": {
        "endpointType": "WebHook",
        "properties": {
          "endpointUrl": "[parameters('endpoint')]"
        }
      },
      "filter": {
        "subjectBeginsWith": "[resourceId('Microsoft.Network/networkSecurityGroups','demoSecurityGroup')]",
        "subjectEndsWith": "",
        "isSubjectCaseSensitive": false,
        "includedEventTypes": [ "All" ]
      }
    }
  }
]

O próximo exemplo de modelo do Resource Manager cria uma assinatura para um armazenamento de blob. Limita os eventos àqueles com um assunto que termina em .jpg.

"resources": [
  {
    "type": "Microsoft.Storage/storageAccounts/providers/eventSubscriptions",
    "name": "[concat(parameters('storageName'), '/Microsoft.EventGrid/', parameters('eventSubName'))]",
    "apiVersion": "2025-02-15",
    "properties": {
      "destination": {
        "endpointType": "WebHook",
        "properties": {
          "endpointUrl": "[parameters('endpoint')]"
        }
      },
      "filter": {
        "subjectEndsWith": ".jpg",
        "subjectBeginsWith": "",
        "isSubjectCaseSensitive": false,
        "includedEventTypes": [ "All" ]
      }
    }
  }
]

Filtrar por operadores e dados

Para obter mais flexibilidade na filtragem, você pode usar operadores e propriedades de dados para filtrar eventos.

Subscrever com filtros avançados

Para saber mais sobre os operadores e as chaves que você pode usar para filtragem avançada, consulte Filtragem avançada.

Estes exemplos criam um tópico personalizado. Eles subscrevem o tópico personalizado e filtram com base num valor no objeto de dados. Os eventos que têm a propriedade color definida como azul, vermelho ou verde são enviados para a assinatura.

Azure PowerShell

Para o PowerShell, utilize:

$topicName = <your-topic-name>
$endpointURL = <endpoint-URL>

New-AzResourceGroup -Name gridResourceGroup -Location eastus2
New-AzEventGridTopic -ResourceGroupName gridResourceGroup -Location eastus2 -Name $topicName

$topicid = (Get-AzEventGridTopic -ResourceGroupName gridResourceGroup -Name $topicName).Id

$expDate = '<mm/dd/yyyy hh:mm:ss>' | Get-Date
$AdvFilter1=@{operatorType="StringIn"; key="data.color"; values=@('blue', 'red', 'green')}

New-AzEventGridSubscription `
  -ResourceId $topicid `
  -EventSubscriptionName <event_subscription_name> `
  -Endpoint $endpointURL `
  -ExpirationDate $expDate `
  -AdvancedFilter @($AdvFilter1)

CLI do Azure

Para a CLI do Azure, utilize:

topicName=<your-topic-name>
endpointURL=<endpoint-URL>

az group create -n gridResourceGroup -l eastus2
az eventgrid topic create --name $topicName -l eastus2 -g gridResourceGroup

topicid=$(az eventgrid topic show --name $topicName -g gridResourceGroup --query id --output tsv)

az eventgrid event-subscription create \
  --source-resource-id $topicid \
  -n demoAdvancedSub \
  --advanced-filter data.color stringin blue red green \
  --endpoint $endpointURL \
  --expiration-date "<yyyy-mm-dd>"

Observe que está definida uma data de expiração para a subscrição.

portal do Azure

1. Na página Subscrição de Eventos , selecione Adicionar novo filtro na secção FILTROS AVANÇADOS .

   

2. Especifique uma chave, operador e valor ou valores a comparar. No exemplo a seguir, data.color é usado como uma chave, String está em como um operador e valores azuis, vermelhos e verdes são especificados para valores.

   

   Nota

   Para saber mais sobre filtros avançados, consulte Compreender a filtragem de eventos para subscrições da Grelha de Eventos.

Testar o filtro

Para testar o filtro, envie um evento com o campo de cor definido como verde. Como o verde é um dos valores do filtro, o evento é enviado para a extremidade.

Azure PowerShell

Para o PowerShell, utilize:

$endpoint = (Get-AzEventGridTopic -ResourceGroupName gridResourceGroup -Name $topicName).Endpoint
$keys = Get-AzEventGridTopicKey -ResourceGroupName gridResourceGroup -Name $topicName

$eventID = Get-Random 99999
$eventDate = Get-Date -Format s

$htbody = @{
    id= $eventID
    eventType="recordInserted"
    subject="myapp/vehicles/cars"
    eventTime= $eventDate
    data= @{
        model="SUV"
        color="green"
    }
    dataVersion="1.0"
}

$body = "["+(ConvertTo-Json $htbody)+"]"

Invoke-WebRequest -Uri $endpoint -Method POST -Body $body -Headers @{"aeg-sas-key" = $keys.Key1}

Para testar um cenário em que o evento não é enviado, envie um evento com o campo de cor definido como amarelo. Amarelo não é um dos valores especificados na assinatura, portanto, o evento não é entregue à sua assinatura.

$htbody = @{
    id= $eventID
    eventType="recordInserted"
    subject="myapp/vehicles/cars"
    eventTime= $eventDate
    data= @{
        model="SUV"
        color="yellow"
    }
    dataVersion="1.0"
}

$body = "["+(ConvertTo-Json $htbody)+"]"

Invoke-WebRequest -Uri $endpoint -Method POST -Body $body -Headers @{"aeg-sas-key" = $keys.Key1}

CLI do Azure

Para a CLI do Azure, utilize:

topicEndpoint=$(az eventgrid topic show --name $topicName -g gridResourceGroup --query "endpoint" --output tsv)
key=$(az eventgrid topic key list --name $topicName -g gridResourceGroup --query "key1" --output tsv)

event='[ {"id": "'"$RANDOM"'", "eventType": "recordInserted", "subject": "myapp/vehicles/cars", "eventTime": "'`date +%Y-%m-%dT%H:%M:%S%z`'", "data":{ "model": "SUV", "color": "green"},"dataVersion": "1.0"} ]'

curl -X POST -H "aeg-sas-key: $key" -d "$event" $topicEndpoint

Para testar um cenário em que o evento não é enviado, envie um evento com o campo de cor definido como amarelo. Amarelo não é um dos valores especificados na assinatura, portanto, o evento não é entregue à sua assinatura.

Para a CLI do Azure, utilize:

event='[ {"id": "'"$RANDOM"'", "eventType": "recordInserted", "subject": "myapp/vehicles/cars", "eventTime": "'`date +%Y-%m-%dT%H:%M:%S%z`'", "data":{ "model": "SUV", "color": "yellow"},"dataVersion": "1.0"} ]'

curl -X POST -H "aeg-sas-key: $key" -d "$event" $topicEndpoint

Conteúdos relacionados

• Compreender a filtragem de eventos para subscrições do Event Grid
• Esquema de grelha de eventos
• Conceitos de Grelha de Eventos