Understand path patterns

Eventarc supports applying a path pattern when filtering. The path pattern syntax allows you to define an expression that matches events. This lets you control the granularity of the Eventarc trigger you are creating, and to capture and act on certain events. For example, you can create a trigger that applies to a single event, such as a change to a specific file, or you can extend the scope of the pattern and create a trigger that applies more broadly.

Apply a path pattern

You can apply a path pattern to filter events when you create a trigger using the Eventarc console page or by running a gcloud command.

For example, you can apply a path pattern when filtering on resource names or database instances (a single instance or a path).

  • Specifying a resource name path pattern applies when creating a trigger for Cloud Audit Logs events and to resourceName values. A resource name indicates the resource being audited through an audit log. Resource names are organized hierarchically using identifiers made up of the ID of the resource itself and the IDs of any parent resources, all separated by forward slashes, like this: /projects/_/buckets/bucket-id/objects/object-id. The filtering done by Eventarc matches patterns based on the values of these identifiers. For more information, see Resource names.

  • Specifying a database instance path pattern applies when creating a trigger for Firebase Realtime Database events and to instance or ref values. A database instance indicates a Firebase Realtime Database instance. You can apply a path pattern to the instance name of the database instance, or a document path for which you want to receive events when data is created, updated, or deleted in that path, or any of its children.

For details, see Create a trigger through the console or Create a trigger using the gcloud CLI.

Identify if you can apply a path pattern

To confirm if you can apply a path pattern to an attribute of an event from a provider, describe the event provider. For example:

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

The output is similar to the following and a pathPatternSupported value of true indicates that you can apply a path pattern:

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

Or, for example:

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

Where the output is similar to the following:

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

For more information, see gcloud eventarc providers describe.

Path pattern syntax

The path pattern syntax is defined as follows:

Path pattern syntax

Pattern /? 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~@#$%&.,?:;+='[]()-]

Legend:

? zero or one
* zero or more
+ one or more
| OR
1 Only listed ASCII characters are supported.

Expressions

An expression can be one of the following segment types and cannot be empty:

  • A single segment Wildcard defined as * matches zero or more characters in the pattern.
  • A MultiSegmentWildcard defined as ** matches zero or more segments in the pattern.
  • A NameSegmentconsists of zero or one * and other characters. This combination allows you to filter by prefix, suffix, or file extension; for example, file-*.txt.

Note that a path can contain many single segment wildcards, but only one multiple segment wildcard. For example, the following path is invalid: /projects/**/buckets/**.

Resource regionality

Resource names can contain location identifiers. For example:

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

However, path pattern matching is constrained by resource regionality. For example, for Cloud Audit Logs triggers, location wildcards only match triggers from the Cloud Audit Logs region, or global triggers.

Capture groups

A CaptureGroup allows you to capture the content of an expression. You do this by assigning the value to a variable name in braces; for example, buckets/{path=**}/files/{filename=file-*.txt}. A single segment wildcard can omit =* in a capture group; for example, /projects/_/buckets/{bucket}/objects/file.*

Examples

The following examples demonstrate how you can and can't use the syntax.

Valid patterns

Pattern Description
/projects/_/buckets/bucket-1/objects/file1.txt Specific resource name.
/projects/_/buckets/bucket-1/objects/* Matches any file in the objects directory.
/projects/_/buckets/bucket-1/objects/*.txt Matches all TXT files in the objects directory.
/projects/_/buckets/bucket-1/objects/file-*.txt Matches all TXT files with prefix file- in the objects directory.
/projects/_/**/file-*.txt Matches any TXT file with prefix file- for all buckets.
/projects/_/buckets/bucket-*/objects/file-*.txt Matches all TXT files with prefix file- for any bucket with prefix bucket-.
/projects/_/buckets/{bucket}/objects/file.*
/projects/_/buckets/{bucket=*}/objects/file.*
/projects/_/buckets/*/objects/{filename=file.*} 		Three different representations of the same filter. Matches any bucket with a file named file of any type. The first two examples also capture the bucket and the last example captures the filename.

Invalid patterns

Pattern Description
/projects/_/buckets/bucket-1/objects/ Empty expression.
/projects//buckets/bucket-1/objects/file1.txt Empty expression.
/projects/_/buckets/bucket**/objects/file1.txt Expression can contain only one *.
/projects/_/buckets/bucket-1/objects/file-*.* Expression can contain only one *.
/projects/**/buckets/** Resource path can contain only one **.
/projects/_/buckets/{=*}/objects/file1.txt Missing ID in segment.
/projects/_/buckets/{bucket=}/objects/file1.txt Empty expression inside a capture group.
/projects/_/buckets/{bucket/objects/file1.txt Capture group not closed.

Pattern matching

Pattern Resource Matches?
/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

What's next