Compartilhar via

Filtros de evento para assinaturas nos tópicos do namespace da Grade de Eventos do Azure

Este artigo descreve diferentes maneiras de especificar filtros em assinaturas de eventos para tópicos de namespace. Os filtros permitem que você envie apenas um subconjunto de eventos que o publicador envia à Grade de Eventos para o ponto de extremidade de destino. Ao criar uma assinatura de evento, você tem três opções para filtragem:

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

Filtragem de tipo de evento

Por padrão, todos os tipos de evento para a origem 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 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 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 .txt para obter apenas eventos relacionados ao carregamento de um arquivo de texto para a conta de armazenamento. Ou você pode filtrar o assunto para obter /blobServices/default/containers/testcontainer todos os eventos desse contêiner, mas não outros contêineres na conta de armazenamento.

Ao publicar eventos em tópicos personalizados, crie assuntos para seus eventos que facilitem que os assinantes saibam 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 estreita 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 obtêm eventos com assuntos como /A/B/C ou /A/D/E. Outros assinantes podem filtrar /A/B para obter um conjunto mais estreito de eventos.

Exemplos (eventos do Armazenamento de Blobs)

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

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

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

Para corresponder a 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 eventos de blobs criados em um contêiner específico, use um subjectBeginsWith filtro como:

/blobServices/default/containers/containername/

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

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

Para corresponder 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 eventos de blobs criados em um contêiner específico compartilhando 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, especifique:

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

Key

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

  • Número

  • booleano

  • String

  • Array. 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 eventos de nuvem, use os seguintes valores para a chave: eventid, source, , eventtypeou eventtypeversiondados 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, EventTypeDataVersionou dados de evento (como).data.key1 Para o esquema de entrada personalizado, use os campos de dados do evento (como data.key1). Para acessar campos na seção de dados, use a . notação (ponto). Por exemplo, data.siteNamedata.appEventTypeDetail.action para acessar siteName ou action para o evento de exemplo 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 dá suporte à filtragem em uma matriz de objetos. Ele só permite cadeia de caracteres, booliano, números e matriz dos mesmos tipos (como matriz de inteiros ou matriz de cadeia de caracteres).

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 counter 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 na matriz de valores de filtro. Aqui está o pseudocódigo com a chave: [v1, v2, v3] e o filtro: [a, b, c]. Todos 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 NumberNotIn será avaliado como true se o valor da chavenão for nenhum dos valores de filtro especificados. No exemplo a seguir, ele verifica se o valor do counter atributo na data seção não é 41 e 0.

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

Se a chave for uma matriz, todos os valores na matriz serão verificados na matriz de valores de filtro. Aqui está o pseudocódigo com a chave: [v1, v2, v3] e o filtro: [a, b, c]. Todos 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
            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 counter 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 pseudocódigo com a chave: [v1, v2, v3]. Todos 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 counter atributo na data seção é maior que 20.

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

Se a chave for uma matriz, todos os valores na matriz serão verificados em relação ao valor do filtro. Aqui está o pseudocódigo com a chave: [v1, v2, v3]. Todos 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

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 counter atributo na data seção é menor ou igual a 100.

"advancedFilters": [{
    "operatorType": "NumberLessThanOrEquals",
    "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 pseudocódigo com a chave: [v1, v2, v3]. Todos 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

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 counter atributo na data seção é maior ou igual a 30.

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

Se a chave for uma matriz, todos os valores na matriz serão verificados em relação ao valor do filtro. Aqui está o pseudocódigo com a chave: [v1, v2, v3]. Todos 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

NumberInRange

O operador NumberInRange 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 key1 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 na matriz de valores de filtro. Aqui está o pseudocódigo com a chave: [v1, v2, v3] e o filtro: uma matriz de intervalos. Neste pseudocódigo e ab são valores baixos e altos de cada intervalo na matriz. Todos 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ão estiver em nenhum dos intervalos de filtro especificados. No exemplo a seguir, ele verifica se o valor do key1 atributo na data seção está em um dos dois intervalos: 3.14159 - 999.95, 3000 - 4000. Se for, o operador retornará 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]]
}

Se a chave for uma matriz, todos os valores na matriz serão verificados na matriz de valores de filtro. Aqui está o pseudocódigo com a chave: [v1, v2, v3] e o filtro: uma matriz de intervalos. Neste pseudocódigo e ab são valores baixos e altos de cada intervalo na matriz. Todos 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
            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 isEnabled 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 booliano do filtro. Aqui está o pseudocódigo com a chave: [v1, v2, v3]. Todos 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 StringContains será avaliado como true se o valor da chavecontiver qualquer um dos valores de filtro especificados (como subcadeias de caracteres). No exemplo a seguir, ele verifica se o valor do key1 atributo na data seção contém uma das subcadeias de caracteres especificadas: microsoft ou azure. Por exemplo, azure data factory tem azure nele.

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

Se a chave for uma matriz, todos os valores na matriz serão verificados na matriz de valores de filtro. Aqui está o pseudocódigo com a chave: [v1, v2, v3] e o filtro: [a,b,c]. Todos 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 key CONTAINS filter
            MATCH

StringNotContains

O operador StringNotContains será avaliado como true se a chavenão contiver os valores de filtro especificados como subcadeias de caracteres. Se a chave contiver um dos valores especificados como uma subcadeia de caracteres, o operador será avaliado como false. No exemplo a seguir, o operador retornará true somente se o key1 valor do atributo na data seção não tiver contoso e fabrikam como subcadeias de caracteres.

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

Se a chave for uma matriz, todos os valores na matriz serão verificados na matriz de valores de filtro. Aqui está o pseudocódigo com a chave: [v1, v2, v3] e o filtro: [a,b,c]. Todos 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 key CONTAINS filter
            FAIL_MATCH

Consulte a seção Limitações para obter a limitação atual desse operador.

StringBeginsWith

O operador StringBeginsWith será avaliado como true se o valor da chavecomeçar com qualquer um dos valores de filtro especificados. No exemplo a seguir, ele verifica se o valor do key1 atributo na data seção começa com event ou message. Por exemplo, event hubs começa com event.

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

Se a chave for uma matriz, todos os valores na matriz serão verificados na matriz de valores de filtro. Aqui está o pseudocódigo com a chave: [v1, v2, v3] e o filtro: [a,b,c]. Todos 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 key BEGINS_WITH filter
            MATCH

StringNotBeginsWith

O operador StringNotBeginsWith será avaliado como true se o valor da chavenão começar com nenhum dos valores de filtro especificados. No exemplo a seguir, ele verifica se o valor do key1 atributo na data seção não começa com event ou message.

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

Se a chave for uma matriz, todos os valores na matriz serão verificados na matriz de valores de filtro. Aqui está o pseudocódigo com a chave: [v1, v2, v3] e o filtro: [a,b,c]. Todos 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 key BEGINS_WITH filter
            FAIL_MATCH

StringEndsWith

O operador StringEndsWith será avaliado como true se o valor da chaveterminar com um dos valores de filtro especificados. No exemplo a seguir, ele verifica se o valor do key1 atributo na data seção termina com jpg ou jpegpng. Por exemplo, eventgrid.png termina com png.

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

Se a chave for uma matriz, todos os valores na matriz serão verificados na matriz de valores de filtro. Aqui está o pseudocódigo com a chave: [v1, v2, v3] e o filtro: [a,b,c]. Todos 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 key ENDS_WITH filter
            MATCH

StringNotEndsWith

O operador StringNotEndsWith será avaliado como true se o valor da chavenão terminar com nenhum dos valores de filtro especificados. No exemplo a seguir, ele verifica se o valor do key1 atributo na data seção não termina com jpg oujpeg.png

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

Se a chave for uma matriz, todos os valores na matriz serão verificados na matriz de valores de filtro. Aqui está o pseudocódigo com a chave: [v1, v2, v3] e o filtro: [a,b,c]. Todos 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 key ENDS_WITH filter
            FAIL_MATCH

StringIn

O operador StringIn verifica se o valor da chavecorresponde exatamente a um dos valores de filtro especificados. No exemplo a seguir, ele verifica se o valor do key1 atributo na data seção é contoso ou fabrikam .factory

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

Se a chave for uma matriz, todos os valores na matriz serão verificados na matriz de valores de filtro. Aqui está o pseudocódigo com a chave: [v1, v2, v3] e o filtro: [a,b,c]. Todos 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

StringNotIn

O operador StringNotIn verifica se o valor da chavenão corresponde a nenhum dos valores de filtro especificados. No exemplo a seguir, ele verifica se o valor do key1 atributo na data seção não aws está e bridge.

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

Se a chave for uma matriz, todos os valores na matriz serão verificados na matriz de valores de filtro. Aqui está o pseudocódigo com a chave: [v1, v2, v3] e o filtro: [a,b,c]. Todos 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
            FAIL_MATCH

Todas as comparações de cadeia de caracteres não diferenciam maiúsculas de minúsculas.

Observação

Se o evento JSON não contiver a chave de filtro avançada, o filtro será avaliado como não correspondido para os seguintes operadores: NumberGreaterThan, NumberGreaterThanOrEquals, NumberLessThan, NumberLessThanOrEquals, NumberIn, BoolEquals, StringContains, StringNotContains, StringBeginsWith, StringNotBeginsWith, StringEndsWith, StringNotEndsWith, StringIn.

O filtro é avaliado como correspondente para os seguintes operadores: NumberNotIn, StringNotIn.

IsNullOrUndefined

O operador IsNullOrUndefined será avaliado como true se o valor da chave for NULL ou indefinido.

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

No exemplo a seguir, a chave1 está ausente, portanto, o operador seria avaliado como true.

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

No exemplo a seguir, key1 é definido como nulo, de modo que o operador seria avaliado como true.

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

Se key1 tiver qualquer outro valor nesses exemplos, o operador será avaliado como false.

IsNotNull

O operador IsNotNull será avaliado como true se o valor da chave não for NULL ou indefinido.

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

OR and AND

Se você especificar um único filtro com vários valores, uma operação OR será executada, portanto, o valor do campo de chave deverá ser um desses valores. Veja um exemplo:

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

Se você especificar vários filtros diferentes, uma operação AND será feita, portanto, cada condição de filtro deverá ser atendida. Veja um exemplo:

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

CloudEvents

Para eventos no esquema CloudEvents, use os seguintes valores para a chave: id, , source, typeou dataschemadados de evento (como data.key1).

Você também pode usar atributos de contexto de extensão no CloudEvents 1.0. No exemplo a seguir, comexampleextension1 e comexampleothervalue são atributos de contexto de extensão.

{
    "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
    }
}

Aqui está um exemplo de como usar um atributo de contexto de extensão em um filtro.

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

Limitações

A filtragem avançada tem as seguintes limitações:

  • 25 filtros avançados e 25 valores de filtro em todos os filtros por assinatura da Grade de Eventos
  • 512 caracteres por valor de cadeia de caracteres
  • Chaves com . (ponto) caractere nelas. Por exemplo: http://schemas.microsoft.com/claims/authnclassreference ou john.doe@contoso.com. Atualmente, não há suporte para caracteres de escape em chaves.

A mesma chave pode ser usada em mais de um filtro.

Próximas etapas

  • Last updated on