Informazioni sui pattern di percorso

Eventarc supporta l'applicazione di un pattern di percorso durante l'applicazione di filtri. La sintassi del pattern del percorso consente di definire un'espressione che corrisponda agli eventi. In questo modo puoi controllare la granularità dell'attivatore Eventarc che stai creando e acquisire ed eseguire azioni su determinati eventi. Ad esempio, puoi creare un trigger che si applica a un singolo evento, ad esempio una modifica a un file specifico, oppure puoi estendere l'ambito del pattern e creare un trigger che si applichi in modo più ampio.

Applicare un pattern del percorso

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

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

  • La specifica di un pattern del percorso del nome della risorsa si applica quando viene creato un attivatore per gli eventi Cloud Audit Logs e ai valori resourceName. Un nome della risorsa indica la risorsa sottoposta a controllo tramite un log di controllo. I nomi delle risorse sono organizzati in modo gerarchico utilizzando identificatori composti dall'ID della risorsa stessa e dagli ID di eventuali risorse principali, il tutto separato da barre, ad esempio: /projects/project-1/datasets/dataset-id. Il filtraggio eseguito da Eventarc corrisponde ai pattern in base ai valori di questi identificatori. Per ulteriori informazioni, consulta la sezione Formato del nome della risorsa in questo documento.

  • La specifica di un pattern del percorso dell'istanza del database si applica quando viene creato un attivatore 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 del database o a un percorso del documento per cui vuoi ricevere eventi quando i dati vengono creati, aggiornati o eliminati in quel percorso o in uno dei suoi elementi secondari.

  • La specifica di un pattern di percorso dell'ID risorsa si applica quando viene creato un attivatore per gli eventi Cloud IoT e ai valori registry e device. Puoi applicare un pattern di percorso per filtrare le modifiche nei registri e nei dispositivi in un registro con la corrispondenza delle caratteri jolly.

Per maggiori dettagli, consulta le istruzioni per creare un attivatore per un provider, un tipo di evento e una destinazione specifici.

Identificare se è possibile applicare un pattern di percorso

Per verificare se puoi applicare un pattern di percorso a un attributo di un evento di un fornitore, descrivi il fornitore di eventi. Ad esempio:

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 di 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

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 ulteriori informazioni, consulta gcloud eventarc providers describe.

Sintassi del pattern del percorso

La sintassi del pattern del percorso è definita come segue:

Sintassi del pattern del percorso

Motivo /? Segment (/Segment)*
Segmento CaptureGroup | Expression
CaptureGroup { ID (= Expression)? }
Espressione Wildcard | MultiSegmentWildcard | NameSegment
NameSegment (Character* Wildcard? Character*)
ID [a-zA-Z0-9_]+
Jolly *
MultiSegmentWildcard **
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ò essere 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 MultiSegmentWildcard definito come ** corrisponde a zero o più segmenti nel pattern.
  • Un NameSegmentè composto da zero o un * e altri caratteri. Questa combinazione consente di filtrare in base a prefisso, suffisso o estensione del file, ad esempio file-*.txt.

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

Regionalità delle risorse

I nomi delle risorse possono contenere identificatori di località. Ad esempio:

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

Tuttavia, la corrispondenza del pattern del percorso è limitata dalla regionalità delle risorse. Ad esempio, per gli attivatori di Cloud Audit Logs, i caratteri jolly per le località corrispondono solo agli attivatori della regione di Cloud Audit Logs o agli attivatori globali.

Gruppi Capture

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

Formato del nome della risorsa

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

Tipo di risorsa Formato del nome completo 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
Bucket1 Cloud Storage //storage.googleapis.com/projects/_/buckets/BUCKET_ID
Oggetti1, 2 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 Compute Engine //compute.googleapis.com/projects/PROJECT_ID/global/networks/NETWORK
Subnet Compute Engine //compute.googleapis.com/projects/PROJECT_ID/regions/REGION/subnetworks/SUBNETWORK
Cluster Google Kubernetes Engine //container.googleapis.com/projects/PROJECT_ID/clusters/CLUSTER_ID
Servizio app App Engine Identity-Aware Proxy //iap.googleapis.com/projects/PROJECT_NUMBER/iap_web/appengine-PROJECT_ID/services/APP_SERVICE_ID
Servizio di backend Compute Engine di 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 Resource Manager //cloudresourcemanager.googleapis.com/organizations/ORGANIZATION_NUMBER
Cartelle di Resource Manager //cloudresourcemanager.googleapis.com/folders/FOLDER_NUMBER
Progetti Resource Manager //cloudresourcemanager.googleapis.com/projects/PROJECT_ID

1 Per Cloud Storage, i nomi delle risorse contengono un carattere underscore (_) anziché un ID progetto. Non puoi sostituire l'underscore con un ID progetto, un nome progetto o un numero di progetto.

2 Utilizza l'intero nome dell'oggetto, incluse le barre. In Cloud Storage, questi caratteri fanno parte del nome dell'oggetto, non sono separatori di percorso.

Esempi

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

Pattern validi

Pattern Descrizione
/projects/project-1/datasets/dataset-1 Nome della risorsa specifica.
/projects/project-1/regions/region-1/subnetworks/* Corrisponde a qualsiasi sottorete 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 prefisso file- nel bucket.
/projects/project-1/serviceAccounts/service-account-email-1/keys/** Corrisponde a qualsiasi chiave per un indirizzo email dell'account di servizio specifico.
/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 prefisso file- per qualsiasi bucket con prefisso bucket-.
/projects/_/buckets/{bucket}/objects/file.*
/projects/_/buckets/{bucket=*}/objects/file.*
/projects/_/buckets/*/objects/{filename=file.*} 		Tre rappresentazioni diverse 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 acquisisce il nome 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 *.
/projects/_/buckets/bucket-1/objects/file-*.* L'espressione può contenere un solo *.
/projects/**/buckets/** Il percorso della risorsa può contenere un solo **.
/projects/_/buckets/{=*}/objects/file1.txt ID mancante nel segmento.
/projects/_/buckets/{bucket=}/objects/file1.txt Espressione vuota all'interno di un gruppo di cattura.
/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