Entenda os padrões de caminho

O Eventarc permite a aplicação de um padrão de caminho durante a filtragem. A sintaxe do padrão de caminho permite definir uma expressão correspondente aos eventos. Isso permite que você controle a granularidade do gatilho do Eventarc que está criando, além de capturar e realizar ações em determinados eventos. Por exemplo, é possível criar um gatilho que se aplique a um único evento, como uma mudança em um arquivo específico, ou ampliar o escopo do padrão e criar um gatilho mais abrangente.

Aplicar um padrão de caminho

É possível aplicar um padrão de caminho para filtrar eventos quando você cria um gatilho usando a página do Eventarc no console do Google Cloud ou executando um comando gcloud.

Por exemplo, é possível aplicar um padrão de caminho ao filtrar nomes de recursos ou instâncias de banco de dados (uma única instância ou caminho).

  • A especificação de um padrão de caminho de nome de recurso se aplica ao criar um gatilho para eventos dos Registros de auditoria do Cloud e aos valores de resourceName. O nome de recurso indica o recurso que está sendo auditado por meio de um registro de auditoria. Os nomes de recursos são organizados hierarquicamente com identificadores compostos pelo ID do próprio recurso e pelos IDs de qualquer recurso pai, todos separados por barras, como a seguir: /projects/project-1/datasets/dataset-id. A filtragem realizada pelo Eventarc faz a correspondência de padrões com base nos valores desses identificadores. Para mais informações, consulte Formato de nomes de recurso neste documento.

  • A especificação de um padrão de caminho de instância de banco de dados se aplica ao criar um gatilho para eventos do Firebase Realtime Database e aos valores de instance ou ref. Uma instância de banco de dados indica uma instância do Firebase Realtime Database. É possível aplicar um padrão de caminho ao nome da instância de banco de dados ou um caminho de documento em que você quer receber eventos quando os dados forem criados, atualizados ou excluídos nesse caminho ou em qualquer um dos filhos dele.

  • A especificação de um padrão de caminho de ID de recurso se aplica ao criar um gatilho para eventos do Cloud IoT e aos valores de registry e device. É possível aplicar um padrão de caminho para filtrar alterações em registros e em dispositivos de um registro, com correspondência de caracteres curinga.

Para mais detalhes, consulte as instruções sobre como criar gatilhos para provedores, tipos de evento e destinos específicos.

Identificar se é possível aplicar um padrão de caminho

Para confirmar se é possível aplicar um padrão de caminho a um atributo de evento de um provedor, descreva o provedor de eventos. Exemplo:

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

A saída é semelhante à seguinte, e um valor pathPatternSupported de true indica que é possível 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

Outro exemplo:

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

O resultado será assim:

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 conferir mais informações, consulte gcloud eventarc providers describe.

Sintaxe do padrão de caminho

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

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*)
Código [a-zA-Z0-9_]+
Curinga *
MultiSegmentWildcard **
Caractere1 [\\w\\s\\t~@#$%&.,?:;+='[]()-]

Legenda:

? zero ou um
* zero ou mais
+ um ou mais
| OU
1 Somente caracteres ASCII listados são compatíveis.

Expressões

Uma expressão pode ser um dos seguintes tipos de segmento e não pode estar em branco:

  • Um único segmento Wildcard definido como * corresponde a zero ou mais caracteres no padrão.
  • Uma MultiSegmentWildcard definida como ** corresponde a zero ou mais segmentos no padrão.
  • Uma NameSegment consiste em zero ou um * e outros caracteres. Essa combinação permite filtrar por prefixo, sufixo ou extensão de arquivo: por exemplo, file-*.txt.

Um caminho pode conter muitos caracteres curinga de segmento único, mas apenas um caractere curinga múltiplo. Por exemplo, o seguinte caminho é inválido: /projects/**/buckets/**.

Regionalidade do recurso

Os nomes dos recursos podem conter identificadores de local. Exemplo:

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

No entanto, a correspondência do padrão de caminho é restrita pela regionalidade dos recursos. Por exemplo, para gatilhos de registros de auditoria do Cloud, os caracteres curinga de local correspondem apenas aos acionadores da região dos registros de auditoria do Cloud ou aos gatilhos globais.

Grupos de captura

Um CaptureGroup permite capturar o conteúdo de uma expressão. Para fazer isso, atribua o valor a um nome de variável entre chaves, por exemplo, buckets/{path=**}/files/{filename=file-*.txt}. Um caractere curinga de segmento único pode omitir =* em um grupo de captura, por exemplo, /projects/_/buckets/{bucket}/objects/file.*.

Formato de nomes de recursos

A tabela a seguir fornece exemplos de nomes de recursos completos para os serviços do Google Cloud usados com mais frequência. Não é uma lista completa. Para saber como os nomes de recursos completos são formatados, consulte a seção Nomes de recursos do guia de design da API.

Tipo de recurso Formato de nome de 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
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
Intervalos do Cloud Storage1 //storage.googleapis.com/projects/_/buckets/BUCKET_ID
Objetos do Cloud Storage1, 2 //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
Serviço de aplicativo do App Engine do Identity-Aware Proxy //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
resourcemanager.folders.* //cloudresourcemanager.googleapis.com/folders/FOLDER_NUMBER
Projetos do Resource Manager //cloudresourcemanager.googleapis.com/projects/PROJECT_ID

1 No Cloud Storage, os nomes de recursos contêm um sublinhado (_), e não um ID de projeto. Não é possível substituir o sublinhado por um ID, nome ou número de projeto.

2 Use todo o nome do objeto, incluindo barras. No Cloud Storage, esses caracteres são parte do nome do objeto, não dos separadores de caminho.

Exemplos

Os exemplos a seguir demonstram como as permissões e restrições de uso da sintaxe.

Padrões válidos

Padrão Descrição
/projects/project-1/datasets/dataset-1 Nome de recurso específico.
/projects/project-1/regions/region-1/subnetworks/* Corresponde a qualquer sub-rede em project-1 e em region-1.
/projects/_/buckets/bucket-1/objects/*.txt Corresponde a todos os arquivos TXT no bucket.
/projects/_/buckets/bucket-1/objects/file-*.txt Retorna todos os arquivos TXT com o prefixo file- no bucket.
/projects/project-1/serviceAccounts/service-account-email-1/keys/** Corresponde a qualquer chave do e-mail de uma conta de serviço específica.
/projects/_/**/file-*.txt Corresponde a qualquer arquivo TXT com o prefixo file- para todos os buckets.
/projects/_/buckets/bucket-*/objects/file-*.txt Corresponde todos os arquivos TXT com o prefixo file- para qualquer bucket 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. Corresponde a qualquer bucket com um arquivo chamado file de qualquer tipo. Os dois primeiros exemplos também capturam o bucket, e o último captura o nome do arquivo.
/projects/project-1/zones/zone-1/instances/** Corresponde a tudo em project-1 e em zone-1.
/projects/*/zones/zone-1/instances/** Corresponde a tudo 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 pode conter apenas um *.
/projects/_/buckets/bucket-1/objects/file-*.* A expressão pode conter apenas um *.
/projects/**/buckets/** O caminho do recurso pode conter apenas um **.
/projects/_/buckets/{=*}/objects/file1.txt ID ausente 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 Corresponde?
/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

A seguir