Compreenda os padrões de caminhos

O Eventarc suporta a aplicação de um padrão de caminho ao filtrar. A sintaxe do padrão de caminho permite-lhe definir uma expressão que corresponda a eventos. Isto permite-lhe controlar a granularidade do acionador do Eventarc que está a criar, bem como capturar e agir em determinados eventos. Por exemplo, pode criar um acionador que se aplique a um único evento, como uma alteração a um ficheiro específico, ou pode expandir o âmbito do padrão e criar um acionador que se aplique de forma mais abrangente.

Aplique um padrão de caminho

Pode aplicar um padrão de caminho para filtrar eventos quando cria um acionador usando a página da consola do Eventarc Google Cloud ou executando um comando gcloud.

Por exemplo, pode aplicar um padrão de caminho ao filtrar por nomes de recursos ou instâncias da base de dados (uma única instância ou um caminho).

  • A especificação de um padrão do caminho do nome do recurso aplica-se quando cria um acionador para eventos dos registos de auditoria da nuvem e a valores resourceName. Um nome do recurso indica o recurso que está a ser auditado através de um registo de auditoria. Os nomes dos recursos estão organizados hierarquicamente através de identificadores compostos pelo ID do próprio recurso e pelos IDs de quaisquer recursos principais, todos separados por barras invertidas, da seguinte forma: /projects/project-1/datasets/dataset-id. A filtragem feita pelo Eventarc corresponde a padrões com base nos valores destes identificadores. Para mais informações, consulte a secção Formato do nome do recurso neste documento.

  • A especificação de um padrão do caminho da instância da base de dados aplica-se quando cria um acionador para eventos da Firebase Realtime Database e a valores instance ou ref. Uma instância da base de dados indica uma instância da Firebase Realtime Database. Pode aplicar um padrão de caminho ao nome da instância da instância da base de dados ou a um caminho de documento para o qual quer receber eventos quando os dados são criados, atualizados ou eliminados nesse caminho ou em qualquer um dos respetivos filhos.

  • A especificação de um padrão do caminho do ID do recurso aplica-se quando cria um acionador para eventos da Cloud IoT e aos valores registry e device. Pode aplicar um padrão de caminho para filtrar alterações em registos e dispositivos num registo com correspondência de carateres universais.

Para ver detalhes, consulte as instruções para criar um acionador para um fornecedor, um tipo de evento e um destino específicos.

Identifique se pode aplicar um padrão de caminho

Para confirmar se pode aplicar um padrão de caminho a um atributo de um evento de um fornecedor, descreva o fornecedor de eventos. Por exemplo:

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

A saída é semelhante à seguinte e um valor de pathPatternSupportedtrue indica que pode aplicar um padrão de caminho:

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

Em alternativa, por exemplo:

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

Quando o resultado é semelhante ao seguinte:

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

Para mais informações, consulte gcloud eventarc providers describe.

Sintaxe do padrão de caminho

A sintaxe do padrão do caminho é definida da seguinte forma:

Sintaxe do padrão de caminho

Padrão /? Segment (/Segment)*
Segmento CaptureGroup | Expression
CaptureGroup { ID (= Expression)? }
Expressão Wildcard | MultiSegmentWildcard | NameSegment
NameSegment (Character* Wildcard? Character*)
ID [a-zA-Z0-9_]+
Caráter universal *
MultiSegmentWildcard **
Caráter1 [\\w\\s\\t~@#$%&.,?:;+='[]()-]

Legenda:

? zero ou um
* zero ou mais
+ um ou mais
| OU
1 Apenas são suportados os carateres ASCII indicados. A correspondência de expressões regulares não é suportada. Metacaracteres suportados:
  • \w refere-se a uma palavra; também representada como [a-zA-Z0-9_]
  • \t refere-se a um separador
  • \s refere-se a um caráter de espaço em branco

Expressões

Uma expressão pode ser um dos seguintes tipos de segmentos e não pode estar vazia:

  • Um único segmento Wildcard definido como * corresponde a zero ou mais carateres no padrão.
  • Um MultiSegmentWildcard definido como ** corresponde a zero ou mais segmentos no padrão.
  • Um NameSegmentconsiste em zero ou um * e outros carateres. Esta combinação permite-lhe filtrar por prefixo, sufixo ou extensão de ficheiro. Por exemplo, file-*.txt.

Tenha em atenção que um caminho pode conter muitos carateres universais de segmento único, mas apenas um caráter universal de vários segmentos. Por exemplo, o seguinte caminho é inválido: /projects/**/buckets/**.

Regionalidade dos recursos

Os nomes dos recursos podem conter identificadores de localização. Por exemplo:

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

No entanto, a correspondência de padrões de caminhos está limitada à regionalidade dos recursos. Por exemplo, para acionadores dos registos de auditoria do Cloud, os carateres universais de localização só correspondem a acionadores da região dos registos de auditoria do Cloud ou a acionadores globais.

Grupos de captura

Um CaptureGroup permite-lhe capturar o conteúdo de uma expressão. Para tal, atribua o valor a um nome de variável entre chavetas; por exemplo, buckets/{path=**}/files/{filename=file-*.txt}. Um caráter universal de segmento único pode omitir =* num grupo de captura; por exemplo, /projects/_/buckets/{bucket}/objects/file.*

Formato do nome do recurso

A tabela seguinte fornece exemplos de nomes de recursos completos paraGoogle Cloud serviços usados frequentemente. Não é uma lista exaustiva. Para saber mais sobre a formatação dos nomes completos dos recursos, consulte a secção Nomes dos recursos do guia de design de APIs.

Tipo do recurso Formato do nome do recurso completo
Conjuntos de dados do BigQuery //bigquery.googleapis.com/projects/PROJECT_ID/datasets/DATASET_ID
Contas do Cloud Billing //cloudbilling.googleapis.com/billingAccounts/BILLING_ACCOUNT_ID
Documentos do Cloud Firestore1 //firestore.googleapis.com/projects/PROJECT_ID/databases/DATABASE_ID/documents/DOCUMENT
Serviços do Cloud Run //run.googleapis.com/projects/PROJECT_ID/locations/LOCATION_ID/services/SERVICE_ID
Instâncias do Cloud SQL //sqladmin.googleapis.com/projects/PROJECT_ID/instances/INSTANCE_ID
Contentores do Cloud Storage 2 //storage.googleapis.com/projects/_/buckets/BUCKET_ID
Objetos do Cloud Storage2, 3 //storage.googleapis.com/projects/_/buckets/BUCKET_ID/objects/OBJECT_ID
Instâncias do Compute Engine //compute.googleapis.com/projects/PROJECT_ID/zones/ZONE/instances/INSTANCE_ID
Redes do Compute Engine //compute.googleapis.com/projects/PROJECT_ID/global/networks/NETWORK
Sub-redes do Compute Engine //compute.googleapis.com/projects/PROJECT_ID/regions/REGION/subnetworks/SUBNETWORK
Clusters do Google Kubernetes Engine //container.googleapis.com/projects/PROJECT_ID/clusters/CLUSTER_ID
Identity-Aware Proxy serviço de apps do App Engine //iap.googleapis.com/projects/PROJECT_NUMBER/iap_web/appengine-PROJECT_ID/services/APP_SERVICE_ID
Serviço de back-end do Compute Engine do IAP //iap.googleapis.com/projects/PROJECT_NUMBER/iap_web/compute/services/BACKEND_SERVICE_ID_OR_NAME
Tópicos do Pub/Sub //pubsub.googleapis.com/projects/PROJECT_ID/topics/TOPIC_ID
Organizações do Resource Manager //cloudresourcemanager.googleapis.com/organizations/ORGANIZATION_NUMBER
Pastas do Resource Manager //cloudresourcemanager.googleapis.com/folders/FOLDER_NUMBER
Projetos do Resource Manager //cloudresourcemanager.googleapis.com/projects/PROJECT_ID

1 Para o Cloud Firestore, não especifique uma barra inicial ao criar um acionador (consulte os exemplos). Para mais informações, consulte o artigo Modelo de dados do Cloud Firestore.

2 Para o Cloud Storage, os nomes dos recursos contêm um sublinhado (_) em vez de um ID do projeto. Não pode substituir o caráter de sublinhado por um ID do projeto, um nome do projeto ou um número do projeto.

3 Para o Cloud Storage, use o nome completo do objeto, incluindo barras invertidas. Estes carateres fazem parte do nome do objeto e não são separadores de caminhos.

Exemplos

Os exemplos seguintes demonstram como pode e não pode usar a sintaxe.

Padrões válidos

Padrão Descrição
/projects/project-1/datasets/dataset-1 Nome do recurso específico.
/projects/project-1/regions/region-1/subnetworks/* Corresponde a qualquer sub-rede em project-1 e region-1.
/projects/_/buckets/bucket-1/objects/*.txt Corresponde a todos os ficheiros TXT no contentor.
/projects/_/buckets/bucket-1/objects/file-*.txt Corresponde a todos os ficheiros TXT com o prefixo file- no contentor.
/projects/project-1/serviceAccounts/service-account-email-1/keys/** Corresponde a qualquer chave para um email de conta de serviço específico.
/projects/_/**/file-*.txt Corresponde a qualquer ficheiro TXT com o prefixo file- para todos os contentores.
/projects/_/buckets/bucket-*/objects/file-*.txt Corresponde a todos os ficheiros TXT com o prefixo file- para qualquer contentor com o prefixo bucket-.
/projects/_/buckets/{bucket}/objects/file.*
/projects/_/buckets/{bucket=*}/objects/file.*
/projects/_/buckets/*/objects/{filename=file.*} 		Três representações diferentes do mesmo filtro. Encontra correspondências de qualquer contentor com um ficheiro denominado file de qualquer tipo. Os dois primeiros exemplos também capturam o contentor e o último exemplo captura o nome do ficheiro.
/projects/project-1/zones/zone-1/instances/** Corresponde a qualquer elemento em project-1 e zone-1.
/projects/*/zones/zone-1/instances/** Corresponde a qualquer elemento em zone-1 em qualquer projeto.

Padrões inválidos

Padrão Descrição
/projects/_/buckets/bucket-1/objects/ Expressão vazia.
/projects//buckets/bucket-1/objects/file1.txt Expressão vazia.
/projects/_/buckets/bucket**/objects/file1.txt A expressão só pode conter um *.
/projects/_/buckets/bucket-1/objects/file-*.* A expressão só pode conter um *.
/projects/**/buckets/** O caminho do recurso só pode conter um **.
/projects/_/buckets/{=*}/objects/file1.txt ID em falta no segmento.
/projects/_/buckets/{bucket=}/objects/file1.txt Expressão vazia dentro de um grupo de captura.
/projects/_/buckets/{bucket/objects/file1.txt O grupo de captura não foi fechado.

Correspondência de padrões

Padrão Recurso Correspondências?
/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
{collection=[clients,users]}/id users/id
clients/id
[clients,users]/id
{collection=clients,users}/id users/id
clients/id
clients,users/id
all users/{id=.*_ +1@gmail.com} all-users/aa_ +1@gmail.com
all users/bb_+1@gmail.com
all users/cc +1@gmail.com

O que se segue?