Comprendre les formats de chemin d'accès

Eventarc permet d'appliquer un format de chemin d'accès lors du filtrage. La syntaxe de modèle de chemin vous permet de définir une expression qui correspond à des événements. Cela vous permet de contrôler la précision du déclencheur Eventarc que vous créez et de capturer et d'agir sur certains événements. Par exemple, vous pouvez créer un déclencheur qui s'applique à un seul événement, tel qu'une modification apportée à un fichier spécifique, ou étendre le champ d'application du modèle et créer un déclencheur plus large.

Appliquer un format de chemin d'accès

Vous pouvez appliquer un modèle de chemin d'accès pour filtrer les évènements lorsque vous créez un déclencheur à l'aide de la page de la console Google Cloud d'Eventarc ou en exécutant une commande gcloud.

Par exemple, vous pouvez appliquer un format de chemin d'accès lorsque vous filtrez sur des noms de ressources ou des instances de base de données (une seule instance ou un chemin d'accès).

  • La spécification d'un modèle de chemin de nom de ressource s'applique lors de la création d'un déclencheur pour les événements Cloud Audit Logs et aux valeurs resourceName. Un nom de ressource indique que la ressource est auditée via un journal d'audit. Les noms de ressource sont organisés hiérarchiquement à l'aide des identifiants composés de l'ID de la ressource elle-même et des ID de toutes les ressources parentes, tous séparés par des barres obliques, comme ceci : /projects/project-1/datasets/dataset-id. Le filtrage effectué par Eventarc correspond aux modèles en fonction des valeurs de ces identifiants. Pour en savoir plus, consultez la section Format du nom des ressources.

  • Le fait de spécifier un modèle de chemin d'accès à l'instance de base de données s'applique lors de la création d'un déclencheur pour les événements Firebase Realtime Database et pour les valeurs instance ou ref. Une instance de base de données indique une instance Firebase Realtime Database. Vous pouvez appliquer un format de chemin d'accès au nom de l'instance de base de données ou à un chemin de document pour lequel vous souhaitez recevoir des événements lorsque des données sont créées, mises à jour ou supprimées dans ce chemin d'accès ou dans l'un de ses enfants.

  • Vous pouvez spécifier un modèle de chemin d'ID de ressource lorsque vous créez un déclencheur pour les événements Cloud IoT et pour les valeurs registry et device. Vous pouvez appliquer un format de chemin d'accès pour filtrer les modifications apportées aux registres et aux appareils d'un registre, avec une correspondance des caractères génériques.

Pour en savoir plus, consultez les instructions afin de créer un déclencheur pour un fournisseur, un type d'événement et une destination spécifiques.

Identifier si vous pouvez appliquer un format de chemin d'accès

Pour vérifier si vous pouvez appliquer un format de chemin à un attribut d'événement d'un fournisseur, décrivez le fournisseur d'événements. Exemple :

gcloud eventarc providers describe cloudaudit.googleapis.com --location=us-central1

Le résultat ressemble à ce qui suit, et la valeur pathPatternSupported de true indique que vous pouvez appliquer un format de chemin :

displayName: Cloud Audit Logs
eventTypes:
- description: An audit log is created that matches the trigger's filter criteria.
  filteringAttributes:
  - attribute: methodName
    description: The identifier of the service's operation.
    required: true
  - attribute: resourceName
    description: The complete path to a resource. Used to filter events for a specific
      resource.
    pathPatternSupported: true
  - attribute: serviceName
    description: The identifier of the Google Cloud service.
    required: true
  - attribute: type
    required: true
  type: google.cloud.audit.log.v1.written
name: projects/project-name/locations/us-central1/providers/cloudaudit.googleapis.com

Ou, par exemple :

gcloud eventarc providers describe firebasedatabase.googleapis.com --location=us-central1

Le résultat ressemble à ce qui suit :

displayName: Firebase Realtime Database
eventTypes:
- description: New data has been created in the database.
  filteringAttributes:
  - attribute: instance
    description: A single database instance.
    pathPatternSupported: true
    required: true
  - attribute: ref
    description: Pattern to match for the database instance.
    pathPatternSupported: true
    required: true
  - attribute: type
    required: true
  type: google.firebase.database.ref.v1.created
[...]

Pour en savoir plus, consultez les sections sur gcloud eventarc providers describe

Syntaxe du format de chemin d'accès

La syntaxe du format de chemin d'accès est définie comme suit :

Syntaxe du format de chemin d'accès

Format /? Segment (/Segment)*
Segment CaptureGroup | Expression
CaptureGroup { ID (= Expression)? }
Expression Wildcard | MultiSegmentWildcard | NameSegment
NameSegment (Character* Wildcard? Character*)
Identifiant [a-zA-Z0-9_]+
Caractère générique *
MultiSegmentWildcard **
Character1 [\\w\\s\\t~@#$%&.,?:;+='[]()-]

Légende :

? zéro ou un
* zéro ou plus
+ un ou plusieurs
| OU
1 Seuls les caractères ASCII répertoriés sont acceptés.

Expressions

Une expression peut correspondre à l'un des types de segments suivants et ne peut pas être vide :

  • Un segment unique Wildcard défini sur * correspond à zéro ou plusieurs caractères du modèle.
  • Une valeur MultiSegmentWildcard définie sur ** correspond à zéro ou plusieurs segments du modèle.
  • Une chaîne NameSegment est constituée de zéro ou un *, et d'autres caractères. Cette combinaison vous permet de filtrer par préfixe, suffixe ou extension de fichier. Exemple : file-*.txt.

Notez qu'un chemin peut contenir de nombreux caractères génériques à un seul segment, mais un seul caractère générique. Par exemple, le chemin d'accès suivant n'est pas valide : /projects/**/buckets/**.

Régionalité des ressources

Les noms des ressources peuvent contenir des identifiants d'emplacement. Exemple :

/projects/$PROJECT_ID/locations/$REGION/triggers/my-trigger

Cependant, la correspondance des formats de chemin est limitée par la régionalisation des ressources. Par exemple, pour les déclencheurs Cloud Audit Logs, les caractères génériques d'emplacement ne correspondent qu'aux déclencheurs de la région Cloud Audit Logs ou aux déclencheurs globaux.

Groupes de capture

Un CaptureGroup vous permet de capturer le contenu d'une expression. Pour ce faire, affectez la valeur à un nom de variable entre accolades. Par exemple : buckets/{path=**}/files/{filename=file-*.txt}. Un seul caractère générique de segment peut omettre =* dans un groupe de capture. Par exemple, /projects/_/buckets/{bucket}/objects/file.*

Format du nom des ressources

Le tableau suivant fournit des exemples de noms de ressources complets pour les services Google Cloud les plus utilisés. Cette liste n'est pas exhaustive. Pour en savoir plus sur le format des noms de ressources complets, consultez la section Noms de ressources du guide de conception d'API.

Type de ressource Format du nom de ressource complet
Ensembles de données BigQuery //bigquery.googleapis.com/projects/PROJECT_ID/datasets/DATASET_ID
Comptes Cloud Billing //cloudbilling.googleapis.com/billingAccounts/BILLING_ACCOUNT_ID
Services Cloud Run //run.googleapis.com/projects/PROJECT_ID/locations/LOCATION_ID/services/SERVICE_ID
Instances Cloud SQL //sqladmin.googleapis.com/projects/PROJECT_ID/instances/INSTANCE_ID
Buckets Cloud Storage1 //storage.googleapis.com/projects/_/buckets/BUCKET_ID
Objets Cloud Storage1, 2 //storage.googleapis.com/projects/_/buckets/BUCKET_ID/objects/OBJECT_ID
Instances Compute Engine //compute.googleapis.com/projects/PROJECT_ID/zones/ZONE/instances/INSTANCE_ID
Réseaux Compute Engine //compute.googleapis.com/projects/PROJECT_ID/global/networks/NETWORK
Sous-réseaux Compute Engine //compute.googleapis.com/projects/PROJECT_ID/regions/REGION/subnetworks/SUBNETWORK
Clusters Google Kubernetes Engine //container.googleapis.com/projects/PROJECT_ID/clusters/CLUSTER_ID
Service de l'application App Engine Identity-Aware Proxy //iap.googleapis.com/projects/PROJECT_NUMBER/iap_web/appengine-PROJECT_ID/services/APP_SERVICE_ID
Service de backend Compute Engine IAP //iap.googleapis.com/projects/PROJECT_NUMBER/iap_web/compute/services/BACKEND_SERVICE_ID_OR_NAME
Sujets Pub/Sub //pubsub.googleapis.com/projects/PROJECT_ID/topics/TOPIC_ID
Organisations Resource Manager //cloudresourcemanager.googleapis.com/organizations/ORGANIZATION_NUMBER
Dossiers Resource Manager //cloudresourcemanager.googleapis.com/folders/FOLDER_NUMBER
Projets Resource Manager //cloudresourcemanager.googleapis.com/projects/PROJECT_ID

1 Pour Cloud Storage, les noms de ressources contiennent un trait de soulignement (_) plutôt qu'un ID de projet. Vous ne pouvez pas remplacer le trait de soulignement par un ID de projet, un nom de projet ni un numéro de projet.

2 Utilisez le nom complet de l'objet, y compris les barres obliques. Dans Cloud Storage, ces caractères sont une partie du nom d'objet, pas des séparateurs de chemin.

Examples

Les exemples suivants montrent comment utiliser et ne pas utiliser la syntaxe.

Formats valides

Format Description
/projects/project-1/datasets/dataset-1 Nom de ressource spécifique.
/projects/project-1/regions/region-1/subnetworks/* Correspond à n'importe quel sous-réseau dans project-1 et region-1.
/projects/_/buckets/bucket-1/objects/*.txt Renvoie tous les fichiers TXT du répertoire.
/projects/_/buckets/bucket-1/objects/file-*.txt Renvoie tous les fichiers TXT comportant le préfixe file- dans le répertoire.
/projects/project-1/serviceAccounts/service-account-email-1/keys/** Correspond à n'importe quelle clé pour l'adresse e-mail d'un compte de service spécifique.
/projects/_/**/file-*.txt Correspond à n'importe quel fichier TXT avec le préfixe file- pour tous les buckets.
/projects/_/buckets/bucket-*/objects/file-*.txt Renvoie tous les fichiers TXT comportant le préfixe file- pour tout bucket portant le préfixe bucket-.
/projects/_/buckets/{bucket}/objects/file.*
/projects/_/buckets/{bucket=*}/objects/file.*
/projects/_/buckets/*/objects/{filename=file.*} 		Trois représentations différentes du même filtre. Correspond à n'importe quel bucket avec un fichier nommé file de n'importe quel type. Les deux premiers exemples capturent également le bucket et le dernier exemple capture le nom du fichier.
/projects/project-1/zones/zone-1/instances/** Correspond à tout ce qui se trouve dans project-1 et zone-1.
/projects/*/zones/zone-1/instances/** Correspond à tout élément dans zone-1 dans n'importe quel projet.

Formats non valides

Format Description
/projects/_/buckets/bucket-1/objects/ Expression vide.
/projects//buckets/bucket-1/objects/file1.txt Expression vide.
/projects/_/buckets/bucket**/objects/file1.txt L'expression ne peut contenir qu'un seul *.
/projects/_/buckets/bucket-1/objects/file-*.* L'expression ne peut contenir qu'un seul *.
/projects/**/buckets/** Le chemin d'accès à la ressource ne peut contenir qu'un seul **.
/projects/_/buckets/{=*}/objects/file1.txt ID manquant dans le segment.
/projects/_/buckets/{bucket=}/objects/file1.txt Expression vide dans un groupe de capture.
/projects/_/buckets/{bucket/objects/file1.txt Le groupe de capture n'est pas fermé.

Correspondance de modèles

Format Resource Correspond ?
/buckets/bucket-1/objects/file1.txt /buckets/bucket-1/objects/file1.txt
/buckets/bucket-1/objects/file2.txt
/buckets/bucket-1/objects/* /buckets/bucket-1/objects/file3.txt
/buckets/bucket-1/objects/file4.jpg
/buckets/bucket-1/objects/files/file4.jpg
/buckets/bucket-1/objects
/buckets/bucket-1/objects/*.txt /buckets/bucket-1/objects/file5.txt
/buckets/bucket-1/objects/file6.jpg
/buckets/bucket-1/objects/file-*.txt /buckets/bucket-1/objects/file-777.txt
/buckets/bucket-1/objects/file-.txt
/buckets/bucket-1/objects/file.txt
/projects/_/**/{filename=file-*.txt} /projects/_/objects/object-1/files/file-9.txt
/projects/_/{ob}jects/**/-+=*/file-9.txt
/projects/_/file-10.txt
/projects/_/files-1/file-1.txt/files-2/file-2.txt
/projects/_//file-1234.txt
/projects/_/files/file-5.txt/file.txt

Étape suivante