Informationen zu Pfadmustern

Eventarc unterstützt das Anwenden eines Pfadmusters beim Filtern. Mit der Pfadmustersyntax können Sie einen Ausdruck definieren, der Ereignissen entspricht. Auf diese Weise können Sie den Detaillierungsgrad des von Ihnen erstellten Eventarc-Triggers steuern und bestimmte Ereignisse erfassen und darauf reagieren. Sie können beispielsweise einen Trigger erstellen, der für ein einzelnes Ereignis gilt, z. B. eine Änderung an einer bestimmten Datei, oder Sie können den Umfang des Musters erweitern und einen Trigger erstellen, der breiter angewendet wird.

Pfadmuster anwenden

Sie können mit einem Pfadmuster Ereignisse filtern, wenn Sie einen Trigger auf der Eventarc-Seite der Google Cloud Console oder mit einem gcloud-Befehl erstellen.

Sie können beispielsweise ein Pfadmuster anwenden, wenn Sie nach Ressourcennamen oder Datenbankinstanzen (eine einzelne Instanz oder ein Pfad) filtern.

  • Die Angabe eines Pfadmusters für Ressourcennamen gilt beim Erstellen eines Triggers für Cloud-Audit-Logereignisse und für resourceName-Werte. Ein Ressourcenname gibt die Ressource an, die über ein Audit-Log geprüft wird. Ein Ressourcenname wird hierarchisch mit Kennungen organisiert, die aus der ID der Ressource und den IDs aller übergeordneten Ressourcen bestehen, getrennt durch Schrägstriche wie in diesem Beispiel: /projects/project-1/datasets/dataset-id. Die von Eventarc durchgeführte Filterung gleicht Muster anhand der Werte dieser Kennungen ab. Weitere Informationen finden Sie in diesem Dokument unter Ressourcennamensformat.

  • Die Angabe eines Pfadmusters für die Datenbankinstanz gilt beim Erstellen eines Triggers für Firebase Realtime Database-Ereignisse und für die Werte instance oder ref. Eine Datenbankinstanz gibt eine Firebase Realtime Database-Instanz an. Sie können ein Pfadmuster auf den Instanznamen der Datenbankinstanz oder einen Dokumentpfad anwenden, für den Sie Ereignisse erhalten möchten, wenn Daten in diesem Pfad oder in einem untergeordneten Element erstellt, aktualisiert oder gelöscht werden. eine

  • Die Angabe eines Ressourcen-ID-Pfadmusters gilt beim Erstellen eines Triggers für Cloud IoT-Ereignisse sowie für die Werte registry und device. Sie können ein Pfadmuster anwenden, um Änderungen in Registries und Geräten in einer Registry mit Platzhalterabgleich zu filtern.

Weitere Informationen finden Sie in der Anleitung zum Erstellen eines Triggers für einen bestimmten Anbieter, Ereignistyp und ein Ziel.

Prüfen, ob Sie ein Pfadmuster anwenden können

Um zu prüfen, ob Sie ein Pfadmuster auf ein Attribut eines Ereignisses von einem Anbieter anwenden können, beschreiben Sie den Ereignisanbieter. Beispiel:

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

Die Ausgabe sieht etwa so aus und der Wert pathPatternSupported von true gibt an, dass Sie ein Pfadmuster anwenden können:

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

Oder zum Beispiel:

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

Die Ausgabe sollte etwa so aussehen:

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
[...]

Weitere Informationen finden Sie unter gcloud eventarc providers describe.

Pfadmustersyntax

Die Pfadmustersyntax ist so definiert:

Pfadmustersyntax

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

Legende:

? null oder eins
* null oder mehr
+ eins oder mehr
| OR
1 Es werden nur die aufgeführten ASCII-Zeichen unterstützt.

Ausdrücke

Ein Ausdruck kann einen der folgenden Segmenttypen haben und nicht leer sein:

  • Eine Einzelsegment-Wildcard, definiert als *, entspricht null oder mehr Zeichen im Muster.
  • Eine als ** definierte MultiSegmentWildcard entspricht null oder mehr Segmenten im Muster.
  • Ein NameSegment besteht aus null oder einem * und anderen Zeichen. Mit dieser Kombination können Sie nach Präfix, Suffix oder Dateiendung filtern. Beispiel: file-*.txt.

Beachten Sie, dass ein Pfad viele Einzelsegment-Platzhalter enthalten kann, aber nur einen Platzhalter mit mehreren Segmenten. Der folgende Pfad ist beispielsweise ungültig: /projects/**/buckets/**.

Ressourcenregionalität

Ressourcennamen können Standortkennungen enthalten. Beispiel:

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

Der Pfadmusterabgleich ist jedoch durch die Ressourcenregionalität eingeschränkt. Bei Cloud-Audit-Logs-Triggern können beispielsweise Standortplatzhalter nur mit Triggern aus der Cloud-Audit-Logs-Region oder mit globalen Triggern übereinstimmen.

Erfassungsgruppen

Mit einer CaptureGroup können Sie den Inhalt eines Ausdrucks erfassen. Weisen Sie dazu den Wert einem Variablennamen in geschweiften Klammern zu. Beispiel: buckets/{path=**}/files/{filename=file-*.txt}. Ein Einzelsegment-Platzhalter kann =* in einer Erfassungsgruppe weglassen. Beispiel: /projects/_/buckets/{bucket}/objects/file.*

Format der Ressourcennamen

Die folgende Tabelle enthält Beispiele für vollständige Ressourcennamen für häufig verwendete Google Cloud-Dienste. Es handelt sich nicht um eine vollständige Liste. Weitere Informationen dazu, wie vollständige Ressourcennamen formatiert werden, finden Sie in der API-Designanleitung im Abschnitt Ressourcennamen.

Ressourcentyp Format von vollständigen Ressourcennamen
BigQuery-Datasets //bigquery.googleapis.com/projects/PROJECT_ID/datasets/DATASET_ID
Cloud-Rechnungskonten //cloudbilling.googleapis.com/billingAccounts/BILLING_ACCOUNT_ID
Cloud Run-Dienste //run.googleapis.com/projects/PROJECT_ID/locations/LOCATION_ID/services/SERVICE_ID
Cloud SQL-Instanzen //sqladmin.googleapis.com/projects/PROJECT_ID/instances/INSTANCE_ID
Cloud Storage-Buckets1 //storage.googleapis.com/projects/_/buckets/BUCKET_ID
Cloud Storage-Objekte1, 2 //storage.googleapis.com/projects/_/buckets/BUCKET_ID/objects/OBJECT_ID
Compute Engine-Instanzen //compute.googleapis.com/projects/PROJECT_ID/zones/ZONE/instances/INSTANCE_ID
Compute Engine-Netzwerke //compute.googleapis.com/projects/PROJECT_ID/global/networks/NETWORK
Compute Engine-Subnetzwerke //compute.googleapis.com/projects/PROJECT_ID/regions/REGION/subnetworks/SUBNETWORK
Google Kubernetes Engine-Cluster //container.googleapis.com/projects/PROJECT_ID/clusters/CLUSTER_ID
Identity-Aware Proxy App Engine-Anwendungsdienst //iap.googleapis.com/projects/PROJECT_NUMBER/iap_web/appengine-PROJECT_ID/services/APP_SERVICE_ID
IAP Compute Engine-Back-End-Dienst //iap.googleapis.com/projects/PROJECT_NUMBER/iap_web/compute/services/BACKEND_SERVICE_ID_OR_NAME
Pub/Sub-Themen //pubsub.googleapis.com/projects/PROJECT_ID/topics/TOPIC_ID
Resource Manager-Organisationen //cloudresourcemanager.googleapis.com/organizations/ORGANIZATION_NUMBER
Resource Manager Ordner //cloudresourcemanager.googleapis.com/folders/FOLDER_NUMBER
Resource Manager-Projekte //cloudresourcemanager.googleapis.com/projects/PROJECT_ID

1 Bei Cloud Storage enthalten Ressourcennamen einen Unterstrich (_) anstelle einer Projekt-ID. Sie können den Unterstrich nicht durch eine Projekt-ID, einen Projektnamen oder eine Projektnummer ersetzen.

2 Verwenden Sie den gesamten Objektnamen, einschließlich Schrägstrichen. In Cloud Storage sind diese Zeichen Teil des Objektnamens, keine Pfadtrennzeichen.

Beispiele

In den folgenden Beispielen wird gezeigt, wie Sie die Syntax verwenden und nicht verwenden können.

Gültige Muster

Muster Beschreibung
/projects/project-1/datasets/dataset-1 Spezifischer Ressourcenname.
/projects/project-1/regions/region-1/subnetworks/* Stimmt mit einem beliebigen Subnetzwerk in project-1 und region-1 überein.
/projects/_/buckets/bucket-1/objects/*.txt Entspricht allen TXT-Dateien im Bucket.
/projects/_/buckets/bucket-1/objects/file-*.txt Entspricht allen TXT-Dateien mit dem Präfix file- im Bucket.
/projects/project-1/serviceAccounts/service-account-email-1/keys/** Entspricht einem beliebigen Schlüssel für eine bestimmte E-Mail-Adresse des Dienstkontos.
/projects/_/**/file-*.txt Entspricht einer beliebigen TXT-Datei mit dem Präfix file- für alle Buckets.
/projects/_/buckets/bucket-*/objects/file-*.txt Entspricht allen TXT-Dateien mit dem Präfix file- für jeden Bucket mit dem Präfix bucket-.
/projects/_/buckets/{bucket}/objects/file.*
/projects/_/buckets/{bucket=*}/objects/file.*
/projects/_/buckets/*/objects/{filename=file.*} 		Drei verschiedene Darstellungen desselben Filters. Entspricht einem beliebigen Bucket mit einer Datei namens file eines beliebigen Typs. In den ersten beiden Beispielen wird auch der Bucket erfasst und im letzten Beispiel wird der Dateiname erfasst.
/projects/project-1/zones/zone-1/instances/** Entspricht allem in project-1 und zone-1.
/projects/*/zones/zone-1/instances/** Entspricht allem in zone-1 in jedem Projekt.

Ungültige Muster

Muster Beschreibung
/projects/_/buckets/bucket-1/objects/ Leerer Ausdruck.
/projects//buckets/bucket-1/objects/file1.txt Leerer Ausdruck.
/projects/_/buckets/bucket**/objects/file1.txt Der Ausdruck kann nur ein * enthalten.
/projects/_/buckets/bucket-1/objects/file-*.* Der Ausdruck kann nur ein * enthalten.
/projects/**/buckets/** Der Ressourcenpfad darf nur ein ** enthalten.
/projects/_/buckets/{=*}/objects/file1.txt Fehlende ID im Segment.
/projects/_/buckets/{bucket=}/objects/file1.txt Leerer Ausdruck in einer Erfassungsgruppe.
/projects/_/buckets/{bucket/objects/file1.txt Erfassungsgruppe nicht geschlossen.

Musterabgleich

Muster Ressource Stimmt überein?
/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

Nächste Schritte