Filtrar eventos do Event Grid

Este artigo mostra como filtrar os eventos que o Event Grid entrega ao seu endpoint ao criar uma assinatura de evento. Você pode filtrar por tipo de evento, por assunto ou por campos e operadores avançados, para que apenas os eventos de seu interesse cheguem ao seu manipulador.

Os exemplos utilizam Azure PowerShell, CLI do Azure, portal Azure e templates Azure Resource Manager (ARM). Use a ferramenta que se encaixar no seu fluxo de trabalho. Para saber mais detalhadamente sobre as opções de filtragem disponíveis, veja Compreender filtragem de eventos para assinaturas do Event Grid.

Pré-requisitos

• Uma assinatura de Azure ativa. Se você não tiver uma conta gratuita, crie uma antes de começar.
• Azure PowerShell ou CLI do Azure instalados, caso você planeje rodar os exemplos do PowerShell ou da CLI. Para mais informações, veja Instalar o módulo PowerShell do Azure Az ou Como instalar a CLI do CLI do Azure.
• Um tópico existente da Grade de Eventos ou tópico do sistema, e um endpoint para receber os eventos filtrados. Alguns exemplos criam o tópico necessário para você.

Filtrar por tipo de evento

Ao criar uma assinatura da Grade de Eventos, você pode especificar quais tipos de eventos devem enviar para o terminal. Os exemplos a seguir criam assinaturas de eventos para um grupo de recursos, mas limitam os eventos enviados para Microsoft.Resources.ResourceWriteFailure e Microsoft.Resources.ResourceWriteSuccess. Se você precisar de mais flexibilidade ao filtrar eventos pelo tipo, consulte Filtrar por operadores avançados e campos de dados.

Azure PowerShell

Para o PowerShell, use o parâmetro -IncludedEventType 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 parâmetro --included-event-types. 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 eventos, conforme mostrado na imagem a seguir.

Para obter uma assinatura existente para um tópico do sistema, use a guia Filtros da página Assinatura de Eventos, conforme mostrado na imagem a seguir.

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

Para especificar um filtro para uma assinatura existente para um tópico personalizado, use a guia Filtros na página Assinatura de Evento.

Modelo do Azure Resource Manager

Para um modelo do Resource Manager, 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. Você pode especificar um valor para corresponder ao início ou fim do assunto. Se você precisar de mais flexibilidade ao filtrar eventos por assunto, consulte Filtrar por operadores avançados e campos de dados.

No exemplo do PowerShell a seguir, você cria uma assinatura de evento que filtra com base no início do assunto. Você usa o parâmetro -SubjectBeginsWith para limitar eventos aos de um recurso específico. Você passa o ID do 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 blobs. Ele limita eventos para aqueles 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 a seguir da CLI do Azure, você cria uma assinatura de evento que filtra pelo início do assunto. Você usa o parâmetro --subject-begins-with para limitar eventos aos de um recurso específico. Você passa o ID do 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 de CLI do Azure cria uma inscrição para um armazenamento de blobs. Ele limita eventos para aqueles 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 assinatura de evento existente:

1. Na página Assinatura do Evento, selecione Habilitar filtragem por assunto.

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 de Correspondência de assunto que diferencia maiúsculas de minúsculas se desejar que o assunto do evento corresponda à diferenciação de maiúsculas de minúsculas dos filtros especificados.

Ao criar uma assinatura de evento, use a guia Filtros no assistente de criação.

Modelo do Azure Resource Manager

No exemplo de modelo do Resource Manager a seguir, você cria uma assinatura de evento que filtra pelo início do assunto. Você usa a propriedade subjectBeginsWith para limitar eventos aos de um recurso específico. Você passa o ID do 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 blobs. Ele limita eventos para aqueles 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 dados e operadores

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

Inscreva-se com filtros avançados

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

Esses exemplos criam um tópico personalizado. Eles se inscrevem no tópico personalizado e filtram por um valor no objeto de dados. Os eventos que possuem a propriedade color definida como azul, vermelha ou verde são enviados para a assinatura.

Azure PowerShell

Para o PowerShell, use:

$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, use:

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 uma data de expiração está definida para a assinatura.

portal do Azure

1. Na página Assinatura do Evento, selecione Adicionar novo filtro na seção FILTROS AVANÇADOS.

   

2. Especifique uma chave, um operador e um valor ou valores para comparar. No exemplo a seguir, data.color é usado como uma chave, A cadeia de caracteres está em como um operador, e os valoresblue, red, e green são especificados como valores.

   

   Observação

   Para saber mais sobre filtros avançados, consulte Compreender a filtragem para assinaturas da Grade de Eventos.

Testar o filtro

Para testar o filtro, envie um evento com o campo de cores definido como verde. Como verde é um dos valores do filtro, o evento é enviado ao endpoint.

Azure PowerShell

Para o PowerShell, use:

$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 cores 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, use:

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 cores 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, use:

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údo relacionado

• Entender a filtragem de eventos para assinaturas da Grade de Eventos
• Esquema do Event Grid
• Conceitos do Event Grid