Filtros de evento para assinaturas para 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 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 de filtragem:
- Tipos de evento
- 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 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
enableAdvancedFilteringOnArrayscomo 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
]
}]
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
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
}]
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
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
}]
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
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
}]
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
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]]
}
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
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"
]
}]
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 key CONTAINS filter
MATCH
StringNotContains
O operador StringNotContains será avaliado como true se a chavenão contiver os valores de filtro especificados como substrings. Se a chave contiver um dos valores especificados como uma substring, o operador será avaliado como false. No exemplo a seguir, o operador retornará true somente se o valor do atributo key1 na seção data 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 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 key CONTAINS filter
FAIL_MATCH
Consulte a seção Limitações para obter a limitação atual deste 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 atributo key1 na seção data 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 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 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 atributo key1 na seção data 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 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 key BEGINS_WITH filter
FAIL_MATCH
StringEndsWith
O operador StringBeginsWith 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 atributo key1 na seção data termina com jpg, jpeg ou 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 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 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 atributo key1 na seção data não termina com jpg, jpeg ou 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 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 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 atributo key1 na seção data é contoso, fabrikam ou 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 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
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 atributo key1 na seção data 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 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
FAIL_MATCH
As comparações de cadeia de caracteres não diferenciam maiúsculas de minúsculas.
Observação
Se o JSON de evento não contiver a chave de filtro avançado, o filtro será avaliado como não correspondente 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 nulo ou indefinido.
{
"operatorType": "IsNullOrUndefined",
"key": "data.key1"
}
No exemplo a seguir, como key1 está ausente, o operador deve ser avaliado como true.
{
"data":
{
"key2": 5
}
}
No exemplo a seguir, como key1 está definida como nula, o operador deve ser 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 nulo ou indefinido.
{
"operatorType": "IsNotNull",
"key": "data.key1"
}
OR e AND
Se você especificar um único filtro com diversos valores, uma operação OR será executada, por isso o valor do campo de chave deve ser um desses valores. Aqui está 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á executada, por isso cada condição de filtro deve 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: eventid, source, eventtype, eventtypeversion ou dados de evento (como data.key1).
Também é possível 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
}
}
Veja a seguir 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
No entanto, o MakeCert tem as seguintes limitações:
- 25 filtros avançados e 25 valores de filtros em todos os filtros por assinatura da Grade de Eventos
- 512 caracteres por valor de cadeia de caracteres
- Chaves com o caractere
.(ponto) . Por exemplo:http://schemas.microsoft.com/claims/authnclassreferenceoujohn.doe@contoso.com. No momento, não há suporte para caracteres de escape em chaves.
A mesma chave pode ser usada em mais de um filtro.