Filtros de eventos para assinaturas de tópicos de 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 enviar apenas um subconjunto de eventos que o editor envia para a Grade de Eventos para o ponto de extremidade de destino. 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
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.
Key
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
enableAdvancedFilteringOnArrayspropriedade 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, , , eventtypeeventtypeversion, sourceou 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, , , EventTypeDataVersionSubjectou 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: e o filtro: [v1, v2, v3] [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
]
}]
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: e o filtro: [v1, v2, v3] [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
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
}]
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
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
}]
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
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
}]
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
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: e o filtro: [v1, v2, v3] uma matriz de intervalos. Neste pseudo código, a e são valores baixos e b 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]]
}
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: e o filtro: [v1, v2, v3] uma matriz de intervalos. Neste pseudo código, a e são valores baixos e b 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
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"
]
}]
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: e o filtro: [v1, v2, v3] [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 key CONTAINS filter
MATCH
StringNotContains
O operador StringNotContains avalia como true se a chave não contiver os valores de filtro especificados como substrings. Se a chave contiver um dos valores especificados como uma substring, o operador avaliará como false. No exemplo a seguir, o operador retorna true somente se o valor do key1 atributo na data seção não tiver contoso e fabrikam como substrings.
"advancedFilters": [{
"operatorType": "StringNotContains",
"key": "data.key1",
"values": [
"contoso",
"fabrikam"
]
}]
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: e o filtro: [v1, v2, v3] [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 key CONTAINS filter
FAIL_MATCH
Consulte a seção Limitações para obter informações sobre a limitação atual deste operador.
StringBeginsCom
O operador StringBeginsWith avalia como true se o valor da chave começar com qualquer um dos valores de filtro especificados. No exemplo a seguir, ele verifica se o key1 valor do 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 em relação à matriz de valores de filtro. Aqui está o pseudo código com a chave: e o filtro: [v1, v2, v3] [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 key BEGINS_WITH filter
MATCH
StringNotBeginsCom
O operador StringNotBeginsWith avalia como true se o valor da chave não começar com nenhum dos valores de filtro especificados. No exemplo a seguir, ele verifica se o key1 valor do 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 em relação à matriz de valores de filtro. Aqui está o pseudo código com a chave: e o filtro: [v1, v2, v3] [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 key BEGINS_WITH filter
FAIL_MATCH
StringEndsCom
O operador StringEndsWith avalia como true se o valor da chave termina com um dos valores de filtro especificados. No exemplo a seguir, ele verifica se o key1 valor do atributo na data seção termina com jpg ou jpeg png. 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 em relação à matriz de valores de filtro. Aqui está o pseudo código com a chave: e o filtro: [v1, v2, v3] [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 key ENDS_WITH filter
MATCH
StringNotEndsWith
O operador StringNotEndsWith avalia como true se o valor da chave não terminar com nenhum dos valores de filtro especificados. No exemplo a seguir, ele verifica se o key1 valor do atributo na data seção não termina com jpg ou ou jpeg 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 em relação à matriz de valores de filtro. Aqui está o pseudo código com a chave: e o filtro: [v1, v2, v3] [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 key ENDS_WITH filter
FAIL_MATCH
StringIn
O operador StringIn verifica se o valor da chave corresponde exatamente a um dos valores de filtro especificados. No exemplo a seguir, ele verifica se o key1 valor do 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 em relação à matriz de valores de filtro. Aqui está o pseudo código com a chave: e o filtro: [v1, v2, v3] [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
StringNotIn
O operador StringNotIn verifica se o valor da chave não corresponde a nenhum dos valores de filtro especificados. No exemplo a seguir, ele verifica se o key1 valor do atributo na data seção não aws é 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 em relação à matriz de valores de filtro. Aqui está o pseudo código com a chave: e o filtro: [v1, v2, v3] [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
FAIL_MATCH
Todas as comparações de cadeia de caracteres não diferenciam maiúsculas de minúsculas.
Nota
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 avalia como true se o valor da chave é NULL ou undefined.
{
"operatorType": "IsNullOrUndefined",
"key": "data.key1"
}
No exemplo a seguir, key1 está faltando, então o operador avaliaria como true.
{
"data":
{
"key2": 5
}
}
No exemplo a seguir, key1 é definido como null, para que o operador avalie como true.
{
"data":
{
"key1": null
}
}
Se key1 tiver qualquer outro valor nesses exemplos, o operador avaliará como false.
IsNotNull
O operador IsNotNull avalia como true se o valor da chave não for NULL ou indefinido.
{
"operatorType": "IsNotNull",
"key": "data.key1"
}
OU E E
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. Eis 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á concluída, portanto, cada condição de filtro deverá ser atendida. Eis um exemplo:
"advancedFilters": [
{
"operatorType": "StringContains",
"key": "Subject",
"values": [
"/providers/microsoft.devtestlab/"
]
},
{
"operatorType": "StringContains",
"key": "Subject",
"values": [
"/providers/Microsoft.Compute/virtualMachines/"
]
}
]
CloudEventos
Para eventos no esquema CloudEvents, use os seguintes valores para a chave: eventid, , eventtype, , sourceeventtypeversionou dados 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 subscrição da Grelha de Eventos
- 512 caracteres por valor de cadeia de caracteres
- Teclas com
.caractere (ponto) neles. Por exemplo:http://schemas.microsoft.com/claims/authnclassreferenceoujohn.doe@contoso.com. Atualmente, não há suporte para caracteres de escape nas chaves.
A mesma chave pode ser usada em mais de um filtro.