Surveiller les modifications d'éléments avec des conditions

Cet article vous explique comment surveiller les modifications des éléments avec une condition personnalisée. Consultez la section générale pour plus d'informations sur les notifications en temps réel.

Présentation

Pour afficher uniquement un certain type de modification pour un élément donné, vous pouvez ajouter une condition à votre flux.

L'objet condition est facultatif. Si un flux ne comporte pas d'objet condition, la destination configurée reçoit toutes les modifications apportées aux éléments.

L'objet condition présente la structure suivante :

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

Title et description sont facultatifs. Ces champs peuvent vous aider à identifier et à décrire la condition.

Le champ expression définit l'expression utilisée pour évaluer la notification dans le CEL (Common Expression Language). L'expression de condition peut contenir plusieurs instructions, qui sont combinées à l'aide d'opérateurs logiques, conformément aux spécifications du langage CEL.

Utiliser le langage CEL

Le CEL (Common Expression Language) est le langage d'expression utilisé pour spécifier une condition de flux. Il est conçu pour exprimer des expressions logiques basées sur des attributs. Pour en savoir plus, consultez la documentation sur la spécification CEL et sa définition de langage.

Dans une condition de flux, le CEL permet de prendre des décisions booléennes basées sur les données d'attribut. Une expression de condition est constituée d'une ou de plusieurs instructions jointes à l'aide d'opérateurs logiques (&&, ||). Chaque instruction exprime une règle de contrôle basée sur des attributs qui s'applique à l'élément TemporalAsset pour déterminer si la notification est envoyée.

Les caractéristiques de langage CEL suivantes sont les plus importantes pour les conditions de flux :

Variables:les conditions utilisent des variables pour exprimer un attribut donné, comme temporal_asset.deleted (de type booléen) ou temporal_asset.asset.name (de type String). Ces variables sont renseignées avec des valeurs en fonction du contexte au moment de l'exécution.
Opérateurs:chaque type de données, tel que String, accepte un ensemble d'opérateurs permettant de créer une expression logique. Le plus souvent, les opérateurs sont utilisés pour comparer la valeur contenue dans une variable avec une valeur littérale, telle que temporal_asset.asset.name == "//cloudresourcemanager.googleapis.com/projects/12345". Dans cet exemple, si la valeur d'entrée de temporal_asset.asset.name est //cloudresourcemanager.googleapis.com/projects/12345, l'expression renvoie true.
Fonctions:une fonction est un opérateur composé pour les types de données acceptant des opérations plus complexes. Dans les expressions de condition, il existe des fonctions prédéfinies qui peuvent être utilisées conjointement avec un type de données spécifique. Par exemple, temporal_asset.asset.name.contains("keyword") utilise une fonction "contains" String et prend la valeur true si la valeur de temporal_asset.asset.name contient "mot clé".
Opérateurs logiques : les conditions sont compatibles avec des opérateurs logiques qui peuvent être utilisés pour créer des expressions logiques complexes à partir d'instructions d'expression simples (&& et ||). Ces opérateurs logiques permettent d'utiliser plusieurs variables d'entrée dans une expression de condition. Par exemple, temporal_asset.deleted && temporal_asset.window.start_time.getFullYear() > 2020 joint deux instructions simples et nécessite que les deux instructions soient remplies pour produire un résultat d'évaluation global true.

Pour en savoir plus sur les caractéristiques des éléments CEL, consultez la section définition de langage.

Utiliser des variables de condition

Les variables de condition vous permettent de créer des conditions sur différents attributs. Les variables de condition acceptées sont les suivantes :

temporal_asset::modification actuelle de l'élément au format TemporalAsset. Si la condition est évaluée à true, le TemporalAsset est envoyé à la destination configurée.

Exemples d'expressions de condition

L'expression de condition suivante envoie des notifications concernant les événements de création :

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

L'expression de condition suivante envoie des notifications pour les ressources situées dans les dossiers 12345 et 23456 :

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

L'expression de condition suivante envoie des notifications lorsque de nouvelles règles autorisées sont ajoutées aux pare-feu, en supposant que asset_type est déjà défini sur compute.googleapis.com/Firewall dans le flux.

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

L'expression de condition suivante envoie des notifications pour les instances de VM avec le type de machine n1-standard-1, en supposant que asset_type est déjà défini sur compute.googleapis.com/Instance dans le flux.

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

L'expression de condition suivante envoie des notifications pour les buckets de stockage avec des stratégies IAM pour allUsers, en supposant que asset_type est défini sur storage.googleapis.com/Bucket et que content_type est défini sur IAM_POLICY dans le flux.

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

L'expression de condition suivante envoie une notification lorsqu'un bucket de stockage dont le libellé contient une clé test est supprimé:

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

Limitations connues

La plupart des noms de variables dans les expressions de condition sont représentés dans snake_case. Les noms de variables des sous-champs de data dans l'objet Resource, qui sont représentés dans camelCase, sont la seule exception.
Les expressions de condition sont limitées à 3 000 caractères.
Certaines validations sur les expressions de condition sont effectuées lors de la création ou de la mise à jour du flux. Toutefois, ces validations ne sont pas exhaustives, en particulier pour les conditions définies dans le champ temporal_asset.asset.resource.data, qui possèdent un type dynamique. Nous vous recommandons d'utiliser des conditions de flux simples avec le asset_type approprié spécifié dans le flux. Si des erreurs de validation se produisent pendant l'évaluation, la notification n'est pas envoyée et les erreurs sont consignées. Découvrez comment afficher les journaux.
Pour les types dynamiques dans temporal_asset.asset.resource.data, les conditions spécifiées sur les champs absents déclenchent des erreurs d'exécution et les notifications ne sont pas publiées. Par exemple, pour la condition temporal_asset.asset.resource.data.name != "my_name", si le champ name est manquant dans une mise à jour, l'évaluation échoue et vous ne recevez pas de notifications. Si votre condition ne fonctionne qu'en présence de certains champs, vérifiez la condition pour vous assurer qu'elle est correctement évaluée.
Les types d'énumérations statiques peuvent être représentés sous forme de noms de chemin complets ou d'entiers bruts. Par exemple, les expressions suivantes sont valides pour prior_asset_state :
```
temporal_asset.prior_asset_state == google.cloud.asset.v1.TemporalAsset.PriorAssetState.DOES_NOT_EXIST
```
et
```
temporal_asset.prior_asset_state == 3
```
Les types d'énumérations dynamiques dans temporal_asset.asset.resource.data sont représentés par des chaînes brutes. Par exemple, l'expression suivante est valide pour le type d'élément cloudresourcemanager.googleapis.com/Project :
```
temporal_asset.asset.resource.data.lifecycleState == "ACTIVE"
```