Como monitorar alterações de recursos com condições

Neste tópico, veja como monitorar alterações de recursos com uma condição personalizada. Saiba mais sobre notificações em tempo real no tópico geral.

Observação: o suporte para condições é limitado. Em alguns casos, a criação ou atualização de feeds com condições pode resultar em um atraso ou ficar temporariamente indisponível.

Informações gerais

Para visualizar apenas determinado tipo de alteração de um determinado recurso, você pode adicionar uma condição ao seu feed.

O objeto condition é opcional. Se um feed não tiver um objeto condition, o destino configurado receberá todas as alterações nos recursos.

O objeto condition tem a seguinte estrutura:

"condition": {
    "title": "...",
    "description": "...",
    "expression": "..."
}

Title e description são opcionais. Esses campos podem ajudar a identificar e descrever a condição.

O campo expression define a expressão usada para avaliar a notificação em Common Expression Language (CEL). A expressão condicional pode conter várias instruções, e as instruções são combinadas com operadores lógicos, seguindo a especificação da linguagem CEL.

Como usar CEL

Common Expression Language (CEL) é a linguagem usada para especificar uma condição de feed. Ela é personalizada para expressar expressões lógicas baseadas em atributos. Para mais informações, consulte a especificação da CEL e a respectiva definição de linguagem (links em inglês).

Em uma condição de feed, a CEL é usada para tomar decisões booleanas com base nos dados do atributo. Uma expressão condicional consiste em uma ou mais instruções que são unidas usando operadores lógicos (&&, ||). Cada instrução expressa uma regra de controle baseada em atributos que se aplica a TemporalAsset para determinar se a notificação será enviada.

Os seguintes recursos de CEL são os mais importantes para as condições do feed:

• Variáveis:as condições usam variáveis para expressar um determinado atributo, como temporal_asset.deleted (do tipo booleano) ou temporal_asset.asset.name (do tipo String). Essas variáveis são preenchidas com valores com base no contexto no ambiente de execução.

• Operadores:cada tipo de dados, como String, oferece suporte a um conjunto de operadores que podem ser usados para criar uma expressão lógica. Geralmente, os operadores são usados para comparar o valor contido em uma variável com um valor literal, como temporal_asset.asset.name == "//cloudresourcemanager.googleapis.com/projects/12345". Neste exemplo, se o valor de entrada de temporal_asset.asset.name for //cloudresourcemanager.googleapis.com/projects/12345, a expressão será avaliada como true.

• Funções:uma função é um operador composto para tipos de dados que aceitam operações mais complexas. Em expressões condicionais, existem funções predefinidas que podem ser usadas em conjunto com um determinado tipo de dados. Por exemplo, temporal_asset.asset.name.contains("keyword") usa uma função "contains" String e será avaliado como true se o valor de temporal_asset.asset.name tiver "palavra-chave".

• Operadores lógicos:as condições são compatíveis com operadores lógicos que podem ser usados para criar expressões lógicas complexas a partir de instruções de expressão simples: && e ||. Esses operadores lógicos possibilitam o uso de várias variáveis de entrada em uma expressão condicional. Por exemplo: temporal_asset.deleted && temporal_asset.window.start_time.getFullYear() > 2020 une duas instruções simples e exige que ambas sejam atendidas para produzir um resultado de avaliação geral true.

Para mais informações sobre os recursos de CEL, consulte a definição de linguagem.

Como usar variáveis de condição

As variáveis de condição permitem que você crie condições em atributos diferentes. As variáveis de condição compatíveis são:

• temporal_asset::a mudança atual do recurso no formato TemporalAsset. Se a condição for avaliada como verdadeira, o TemporalAsset será enviado para o destino configurado.

Exemplo de expressões condicionais

A expressão de condição a seguir envia notificações sobre eventos de criação:

temporal_asset.deleted == false &&
temporal_asset.prior_asset_state == google.cloud.asset.v1.TemporalAsset.PriorAssetState.DOES_NOT_EXIST

A expressão de condição a seguir envia notificações para os recursos que estão localizados nas pastas 12345 e 23456:

"folders/12345" in temporal_asset.asset.ancestors ||
"folders/23456" in temporal_asset.asset.ancestors

A expressão de condição a seguir enviará notificações quando novas regras permitidas forem adicionadas aos firewalls, supondo que asset_type já esteja definido como compute.googleapis.com/Firewall no feed.

size(temporal_asset.asset.resource.data.allowed) >
size(temporal_asset.prior_asset.resource.data.allowed)

A expressão de condição a seguir envia notificações para instâncias de VM com o tipo de máquina n1-standard-1, supondo que asset_type já esteja definido como compute.googleapis.com/Instance no feed.

temporal_asset.asset.resource.data.machineType.endsWith('/machineTypes/n1-standard-1')

A expressão de condição a seguir envia notificações para buckets de armazenamento com qualquer política de IAM para allUsers, supondo que asset_type esteja definido como storage.googleapis.com/Bucket e content_type esteja definido como IAM_POLICY no feed.

temporal_asset.asset.iam_policy.bindings.exists(b, b.members.exists(m, m == "allUsers"))

A expressão de condição a seguir envia uma notificação quando um bucket de armazenamento com uma chave test no rótulo é excluído:

temporal_asset.deleted == true && temporal_asset.prior_asset_state == google.cloud.asset.v1.TemporalAsset.PriorAssetState.PRESENT && "test" in temporal_asset.prior_asset.resource.data.labels

Limitações conhecidas

• A maioria dos nomes de variáveis em expressões de condição é representada em snake_case. A única exceção são os nomes de variáveis dos subcampos de data no objeto Recurso, representados em camelCase.

• As expressões de condição têm um limite de 3.000 caracteres.

• Algumas validações em expressões de condição são realizadas durante a criação/atualização do feed. No entanto, essas validações não são abrangentes, especialmente para condições definidas no campo temporal_asset.asset.resource.data, que tem tipo dinâmico. Recomendamos condições de feed simples com o asset_type adequado especificado no feed. Se ocorrerem erros de validação durante o tempo de avaliação, a notificação não será enviada e os erros serão registrados. Saiba mais sobre como visualizar registros.

• Para tipos dinâmicos em temporal_asset.asset.resource.data, as condições especificadas em campos ausentes acionam erros de ambiente de execução, e as notificações não são publicadas. Por exemplo, para a condição temporal_asset.asset.resource.data.name != "my_name", se o campo name estiver ausente em uma atualização, a avaliação falhará e você não receberá notificações. Se sua condição funcionar apenas na presença de determinados campos, verifique a existência na condição para garantir que ela seja avaliada corretamente.

• Os tipos de enumeração estáticos podem ser representados como nomes de caminho totalmente qualificados ou inteiros brutos. Por exemplo, as expressões a seguir são válidas para prior_asset_state:

  temporal_asset.prior_asset_state == google.cloud.asset.v1.TemporalAsset.PriorAssetState.DOES_NOT_EXIST
  

  e

  temporal_asset.prior_asset_state == 3
  

  Os tipos de enumeração dinâmica em temporal_asset.asset.resource.data são representados como strings brutas. Por exemplo, a expressão a seguir é válida para o tipo de recurso cloudresourcemanager.googleapis.com/Project:

  temporal_asset.asset.resource.data.lifecycleState == "ACTIVE"