Informazioni sui pattern dei percorsi

Eventarc supporta l'applicazione di un pattern del percorso durante il filtraggio. La sintassi del pattern del percorso consente di definire un'espressione che corrisponde agli eventi. Ciò consente di controllare la granularità dell'attivatore Eventarc che stai creando e di acquisire e agire su determinati eventi. Ad esempio, puoi creare un trigger che si applichi a un singolo evento, come una modifica a un file specifico, oppure estendere l'ambito del pattern e creare un trigger che si applichi in modo più ampio.

Applica un pattern del percorso

Puoi applicare un pattern del percorso per filtrare gli eventi quando crei un trigger utilizzando la pagina della console Google Cloud Eventarc o eseguendo un comando gcloud.

Ad esempio, puoi applicare un pattern di percorso quando applichi un filtro in base ai nomi di risorse o alle istanze di database (una singola istanza o un percorso).

  • Se si specifica un trigger di eventi del log di controllo Cloud e ai valori resourceName, si specifica un pattern del percorso del nome della risorsa. Il nome di una risorsa indica che la risorsa viene controllata tramite un log di controllo. I nomi delle risorse sono organizzati in modo gerarchico utilizzando identificatori costituiti dall'ID della risorsa stessa e gli ID di eventuali risorse padre, tutti separati da barre, come questo: /projects/project-1/datasets/dataset-id. Il filtro eseguito da Eventarc associa i pattern in base ai valori di questi identificatori. Per ulteriori informazioni, consulta questo documento sul formato del nome della risorsa.

  • La specifica di un pattern del percorso dell'istanza del database si applica quando crei un trigger per gli eventi di Firebase Realtime Database e ai valori instance o ref. Un'istanza di database indica un'istanza di Firebase Realtime Database. Puoi applicare un pattern di percorso al nome dell'istanza di database o al percorso di un documento per cui vuoi ricevere eventi quando i dati vengono creati, aggiornati o eliminati in quel percorso o in una qualsiasi delle sue istanze secondarie.

  • La specifica di un pattern del percorso dell'ID risorsa si applica durante la creazione di un trigger per gli eventi Cloud IoT e ai valori registry e device. Puoi applicare un pattern del percorso per filtrare le modifiche nei registry e i dispositivi in un registro, con corrispondenza con caratteri jolly.

Per informazioni dettagliate, consulta le istruzioni per creare un trigger per un provider, un tipo di evento e una destinazione specifici.

Verifica se puoi applicare un pattern del percorso

Per verificare se puoi applicare un pattern del percorso a un attributo di un evento da un provider, descrivi il provider di eventi. Ecco alcuni esempi:

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

L'output è simile al seguente e un valore pathPatternSupported di true indica che puoi applicare un pattern del percorso:

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

Oppure, ad esempio:

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

Dove l'output è simile al seguente:

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

Per maggiori informazioni, consulta gcloud eventarc providers describe.

Sintassi dei pattern dei percorsi

La sintassi del pattern del percorso è definita come segue:

Sintassi dei pattern dei percorsi

Sequenza /? Segment (/Segment)*
Segmento CaptureGroup | Expression
Acquisisci gruppo { ID (= Expression)? }
Espressione Wildcard | MultiSegmentWildcard | NameSegment
Segmento (Character* Wildcard? Character*)
ID [a-zA-Z0-9_]+
Carattere jolly *
Wildcard multisegmento **
Carattere1 [\\w\\s\\t~@#$%&.,?:;+='[]()-]

Legenda:

? zero o uno
* zero o più
+ uno o più
| OPPURE
1 Sono supportati solo i caratteri ASCII elencati.

Espressioni

Un'espressione può rientrare in uno dei seguenti tipi di segmento e non può essere vuota:

  • Un singolo segmento Wildcard definito come * corrisponde a zero o più caratteri nel pattern.
  • Un valore MultiSegmentWildcard definito come ** corrisponde a zero o più segmenti nel pattern.
  • Un NameSegment è costituito da zero o da * e altri caratteri. Questa combinazione consente di filtrare in base al prefisso, al suffisso o all'estensione del file, ad esempio file-*.txt.

Tieni presente che un percorso può contenere molti caratteri jolly relativi a un singolo segmento, ma un solo carattere jolly a più segmenti. Ad esempio, il seguente percorso non è valido: /projects/**/buckets/**.

Regione delle risorse

I nomi delle risorse possono contenere identificatori di località. Ecco alcuni esempi:

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

Tuttavia, la corrispondenza del pattern del percorso è vincolata dalla regione della risorsa. Ad esempio, per gli attivatori di Cloud Audit Logs, i caratteri jolly nella località corrispondono solo agli attivatori della regione Cloud Audit Logs o agli attivatori globali.

Acquisisci gruppi

CaptureGroup consente di acquisire il contenuto di un'espressione. Per farlo, devi assegnare un valore al nome della variabile tra parentesi graffe, ad esempio buckets/{path=**}/files/{filename=file-*.txt}. Un carattere jolly per un singolo segmento può omettere =* in un gruppo di acquisizione; ad esempio, /projects/_/buckets/{bucket}/objects/file.*

Formato del nome della risorsa

La seguente tabella fornisce esempi di nomi completi delle risorse per i servizi Google Cloud di uso comune. Non si tratta di un elenco esaustivo. Per scoprire di più su come vengono formattati i nomi completi delle risorse, consulta la sezione Nomi delle risorse della guida alla progettazione delle risorse.

Tipo di risorsa Formato completo del nome della risorsa
Set di dati BigQuery //bigquery.googleapis.com/projects/PROJECT_ID/datasets/DATASET_ID
Account di fatturazione Cloud //cloudbilling.googleapis.com/billingAccounts/BILLING_ACCOUNT_ID
Servizi Cloud Run //run.googleapis.com/projects/PROJECT_ID/locations/LOCATION_ID/services/SERVICE_ID
Istanze Cloud SQL //sqladmin.googleapis.com/projects/PROJECT_ID/instances/INSTANCE_ID
Bucket Cloud Storage1 //storage.googleapis.com/projects/_/buckets/BUCKET_ID
Oggetti1, 2 di Cloud Storage //storage.googleapis.com/projects/_/buckets/BUCKET_ID/objects/OBJECT_ID
Istanze Compute Engine //compute.googleapis.com/projects/PROJECT_ID/zones/ZONE/instances/INSTANCE_ID
Reti di Compute Engine //compute.googleapis.com/projects/PROJECT_ID/global/networks/NETWORK
Subnet di Compute Engine //compute.googleapis.com/projects/PROJECT_ID/regions/REGION/subnetworks/SUBNETWORK
Cluster di Google Kubernetes Engine //container.googleapis.com/projects/PROJECT_ID/clusters/CLUSTER_ID
Identity-Aware Proxy servizio app di App Engine //iap.googleapis.com/projects/PROJECT_NUMBER/iap_web/appengine-PROJECT_ID/services/APP_SERVICE_ID
Servizio di backend Compute Engine IAP //iap.googleapis.com/projects/PROJECT_NUMBER/iap_web/compute/services/BACKEND_SERVICE_ID_OR_NAME
Argomenti Pub/Sub //pubsub.googleapis.com/projects/PROJECT_ID/topics/TOPIC_ID
Organizzazioni di Resource Manager //cloudresourcemanager.googleapis.com/organizations/ORGANIZATION_NUMBER
Cartelle di Resource Manager //cloudresourcemanager.googleapis.com/folders/FOLDER_NUMBER
Progetti di Resource Manager //cloudresourcemanager.googleapis.com/projects/PROJECT_ID

1 Per Cloud Storage, i nomi delle risorse contengono un trattino basso (_) anziché un ID progetto. Non puoi sostituire il trattino basso con un ID, un nome o un numero di progetto.

2 Utilizza il nome completo dell'oggetto, comprese le barre. In Cloud Storage, questi caratteri fanno parte del nome dell'oggetto, non dei separatori.

Esempi

I seguenti esempi mostrano come utilizzare e non utilizzare la sintassi.

Pattern validi

Pattern Descrizione
/projects/project-1/datasets/dataset-1 Nome risorsa specifica.
/projects/project-1/regions/region-1/subnetworks/* Corrisponde a qualsiasi subnet in project-1 e region-1.
/projects/_/buckets/bucket-1/objects/*.txt Corrisponde a tutti i file TXT nel bucket.
/projects/_/buckets/bucket-1/objects/file-*.txt Corrisponde a tutti i file TXT con il prefisso file- nel bucket.
/projects/project-1/serviceAccounts/service-account-email-1/keys/** Corrisponde a qualsiasi chiave per l'email di uno specifico account di servizio.
/projects/_/**/file-*.txt Corrisponde a qualsiasi file TXT con prefisso file- per tutti i bucket.
/projects/_/buckets/bucket-*/objects/file-*.txt Corrisponde a tutti i file TXT con il prefisso file- per qualsiasi bucket con prefisso bucket-.
/projects/_/buckets/{bucket}/objects/file.*
/projects/_/buckets/{bucket=*}/objects/file.*
/projects/_/buckets/*/objects/{filename=file.*} 		Tre diverse rappresentazioni dello stesso filtro. Corrisponde a qualsiasi bucket con un file denominato file di qualsiasi tipo. I primi due esempi acquisiscono anche il bucket, mentre l'ultimo esempio acquisisce il nome del file.
/projects/project-1/zones/zone-1/instances/** Corrisponde a qualsiasi elemento in project-1 e zone-1.
/projects/*/zones/zone-1/instances/** Corrisponde a qualsiasi elemento in zone-1 in qualsiasi progetto.

Pattern non validi

Pattern Descrizione
/projects/_/buckets/bucket-1/objects/ Espressione vuota.
/projects//buckets/bucket-1/objects/file1.txt Espressione vuota.
/projects/_/buckets/bucket**/objects/file1.txt L'espressione può contenere un solo elemento *.
/projects/_/buckets/bucket-1/objects/file-*.* L'espressione può contenere un solo elemento *.
/projects/**/buckets/** Il percorso della risorsa può contenere un solo elemento **.
/projects/_/buckets/{=*}/objects/file1.txt ID mancante nel segmento.
/projects/_/buckets/{bucket=}/objects/file1.txt Espressione vuota all'interno di un gruppo di acquisizione.
/projects/_/buckets/{bucket/objects/file1.txt Gruppo di acquisizione non chiuso.

Corrispondenza di pattern

Pattern Risorsa Corrispondenze?
/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

Passaggi successivi