Compreender a filtragem para assinaturas da Grade de Eventos

Artigo
11/15/2023

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

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

Modelo do Azure Resource Manager

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

Conta de Armazenamento do Azure
Tópico do sistema para a conta de armazenamento
Assinatura do evento para o tópico do sistema. Você verá a subseção filter na seção de assinatura do evento.

No exemplo a seguir, a assinatura do evento filtra eventos Microsoft.Storage.BlobCreated e 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'))]"
      ]
    }
  ]
}

Filtragem de tipo de evento

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

A sintaxe JSON para filtrar por tipo de evento é:

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

Filtro de assunto

Para filtragem simples por assunto, especifique um valor inicial ou final para o assunto. Por exemplo, você pode especificar o assunto que termina com .txt para obter apenas os eventos relacionados ao carregamento 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 para outros contêineres na conta de armazenamento.

Ao publicar eventos em tópicos personalizados, crie assuntos para os eventos que tornem mais fácil aos assinantes reconhecer se estão interessados no evento. Os assinantes usam a propriedade assunto para filtrar e rotear eventos. Considere adicionar o caminho do acontecimento do evento para que os assinante possam filtrar por segmentos desse caminho. O caminho permite que os assinantes filtrem eventos de maneira 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 conjunto amplo de eventos. Esses assinantes recebem eventos com assuntos como /A/B/C ou /A/D/E. Outros assinantes podem filtrar por /A/B para obter um conjunto de eventos mais restrito.

Exemplos (eventos de Armazenamento de Blobs)

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

O assunto de eventos do Armazenamento de Blobs usa o formato:

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

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

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

/blobServices/default/containers/containerprefix

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

/blobServices/default/containers/containername/

Para corresponder os eventos de blobs criados em um contêiner específico que compartilha um prefixo de nome de blob, use um filtro subjectBeginsWith como:

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

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

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

Para corresponder os eventos de blobs criados em um contêiner específico que compartilha um sufixo de nome de blob, use um filtro subjectEndsWith 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 o:

tipo de operador: o tipo de comparação.
chave – o campo nos dados do evento que você está usando para filtragem. Pode ser um número, um booliano, uma cadeia de caracteres ou uma matriz.
valores – os valores a serem comparados com a chave.

Chave

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

Número
Boolean
String

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

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

Para eventos no esquema Eventos de Nuvem, 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 da 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 personalizada, use os campos de dados de evento (comodata.key1). Para acessar campos na seção de dados, use a notação . (ponto). Por exemplo, data.siteName, data.appEventTypeDetail.action para acessar siteName ou action para a amostra de evento a seguir.

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

Observação

A Grade de Eventos não suporta a filtragem em uma matriz de objetos. Ela só permite String, Boolean, Numbers e Array dos mesmos tipos (como integer array ou string array).

Valores

Os valores podem ser: número, cadeia de caracteres, booliano ou matriz.

Operadores

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

NumberIn

O operador NumberIn será avaliado como true se o valor da chave for um dos valores de filtro especificados. No exemplo a seguir, ele verifica se o valor do atributo counter na seção data é 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 dos valores de filtro. Este é o pseudocódigo com a chave: [v1, v2, v3] e o filtro: [a, b, c]. Os valores de 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

NumberNotIn

O operador NumberNotIn será avaliado como true se o valor da chavenão for nenhum dos valores defiltro especificados. No exemplo a seguir, ele verifica se o valor do atributo counter na seção data 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

NumberLessThan

O operador NumberLessThan será avaliado como true se o valor da chave for menor que o valor de filtro especificado. No exemplo a seguir, ele verifica se o valor do atributo counter na seção data é 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 de filtro. Este é o pseudocódigo com a chave: [v1, v2, v3]. Os valores de 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

NumberGreaterThan

O operador NumberGreaterThan será avaliado como true se o valor da chave for maior que o valor de filtro especificado. No exemplo a seguir, ele verifica se o valor do atributo counter na seção data é 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 será avaliado como true se o valor da chave for menor ou igual ao valor de filtro especificado. No exemplo a seguir, ele verifica se o valor do atributo counter na seção data é 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 será avaliado como true se o valor da chave for maior ou igual ao valor de filtro especificado. No exemplo a seguir, ele verifica se o valor do atributo counter na seção data é 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 operadorNumberInRange será avaliado como true se o valor da chave estiver em um dos intervalos de filtro especificados. No exemplo a seguir, ele verifica se o valor do atributo key1 na seção data 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 propriedade values é uma matriz de intervalos. No exemplo anterior, ela é uma matriz de dois intervalos. Veja a seguir um exemplo de matriz com um intervalo a ser verificado.

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 dos valores de filtro. Este é o pseudocódigo com a chave: [v1, v2, v3] e o filtro: uma matriz de intervalos. Nesse pseudo-código, a e b são valores altos e baixos de cada intervalo na matriz. Os valores de 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

NumberNotInRange

O operador NumberNotInRange será avaliado como true se o valor da chavenãoestiver em um dos intervalos de filtro especificados. No exemplo a seguir, ele verifica se o valor do atributo key1 na seção data está em um dos dois intervalos: 3.14159 - 999.95, 3000 - 4000. Nesse caso, o operador retornará false.

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

A propriedade values é uma matriz de intervalos. No exemplo anterior, ela é uma matriz de dois intervalos. Veja a seguir um exemplo de matriz com um intervalo a ser verificado.

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 boolianos é:

BoolEquals

O operador BoolEquals será avaliado como true se o valor da chave for o filtro de valor booliano especificado. No exemplo a seguir, ele verifica se o valor do atributo isEnabled na seção data é 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 booliano do filtro. Este é o pseudocódigo com a chave: [v1, v2, v3]. Os valores de 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 cadeias de caracteres são:

StringContains

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

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