Informationen zu Pfadmustern

Vorschau

Diese Funktion unterliegt den „Nutzungsbedingungen für Pre-GA-Angebote“ im Abschnitt „Allgemeine Nutzungsbedingungen“ der dienstspezifischen Nutzungsbedingungen. Pre-GA-Funktionen sind „wie besehen“ verfügbar und werden möglicherweise nur eingeschränkt unterstützt. Weitere Informationen finden Sie in den Beschreibungen der Startphase.

Eventarc unterstützt das Anwenden eines Pfadmusters beim Filtern. Mit der Pfadmustersyntax können Sie einen Ausdruck definieren, der Ereignissen abgleicht. 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 ein Pfadmuster beispielsweise anwenden, wenn Sie nach Ressourcennamen oder Datenbankinstanzen (eine einzelne Instanz oder ein Pfad) filtern.

• Die Angabe eines Pfadmusters für den Ressourcennamen gilt beim Erstellen eines Triggers für Cloud-Audit-Log-Ereignisse und für resourceName-Werte. Ein Ressourcenname gibt die Ressource an, die durch 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 Format der Ressourcennamen.

• 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 bezieht sich auf eine Firebase Realtime Database-Instanz. Sie können ein Pfadmuster auf den Instanznamen der Datenbankinstanz oder auf 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.

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

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

Prüfen, ob ein Pfadmuster angewendet werden kann

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 pathPatternSupported-Wert true gibt an, dass Sie das 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:

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

Legende:

?	null oder eins
*	null oder mehr
+	eins oder mehr
|	ODER

¹ 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.*

Hinweis: Erfassungsgruppen haben keine semantische Bedeutung. Es wird nur die Syntax unterstützt.

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-Buckets^1	//storage.googleapis.com/projects/_/buckets/BUCKET_ID
Cloud Storage-Objekte^1, 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

¹ 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.

² 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/*	Entspricht jedem Subnetzwerk in project-1 und region-1.
/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 Dienstkonto-E-Mail-Adresse.
/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

• Eine Liste der von Eventarc unterstützten Ereignisse finden Sie unter Von Eventarc unterstützte Ereignistypen.