Comprende los patrones de ruta de acceso

Eventarc admite la aplicación de un patrón de ruta de acceso cuando se filtra. La sintaxis del patrón de ruta de acceso te permite definir una expresión que coincida con eventos. Esto te permite controlar el nivel de detalle del activador de Eventarc que estás creando, así como capturar y reaccionar a ciertos eventos. Por ejemplo, puedes crear un activador que se aplique a un solo evento, como un cambio en un archivo específico o puedes extender el alcance del patrón y crear un activador que se aplique de manera más amplia.

Aplica un patrón de ruta de acceso

Puedes aplicar un patrón de ruta de acceso para filtrar los recursos cuando creas un activador mediante la página de la consola de Google Cloud de Eventarc o si ejecutas un comando de gcloud.

Por ejemplo, puedes aplicar un patrón de ruta de acceso cuando filtras nombres de recursos o instancias de base de datos (una sola instancia o una ruta).

  • Especificar un patrón de ruta de nombre de recurso se aplica cuando se crea un activador para eventos de Registros de auditoría de Cloud y a valores resourceName. El nombre de un recurso indica el recurso que se audita a través de un registro de auditoría. Un nombre de recurso se organiza de forma jerárquica mediante identificadores compuestos por el ID del recurso y los ID de los recursos superiores, todos separados por barras diagonales, de la siguiente manera: /projects/project-1/datasets/dataset-id. El filtrado que realiza Eventarc coincide con los patrones según los valores de estos identificadores. Para obtener más información, en este documento, consulta Formato de nombre de recurso.

  • La especificación de un patrón de ruta de instancia de base de datos se aplica cuando se crea un activador para eventos de Firebase Realtime Database y a valores instance o ref. Una instancia de base de datos indica una instancia de Firebase Realtime Database. Puedes aplicar un patrón de ruta de acceso al nombre de la instancia de la instancia de base de datos o una ruta de acceso de documento para la que deseas recibir eventos cuando se crean, actualizan o borran datos en esa ruta o en cualquiera de sus elementos secundarios. .

  • La especificación de un patrón de ruta de ID de recurso se aplica cuando se crea un activador para eventos de Cloud IoT y a los valores registry y device. Puedes aplicar un patrón de ruta de acceso para filtrar los cambios en los registros y dispositivos en un registro, con coincidencia de comodines.

Si deseas obtener detalles, consulta las instrucciones para crear un activador para un proveedor, un tipo de evento y un destino específicos.

Identifica si puedes aplicar un patrón de ruta de acceso

Para confirmar si puedes aplicar un patrón de ruta de acceso a un atributo de un evento de un proveedor, describe el proveedor de eventos. Por ejemplo:

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

El resultado es similar al siguiente y un valor pathPatternSupported de true indica que puedes aplicar un patrón de ruta de acceso:

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

o, por ejemplo:

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

El resultado es similar al siguiente:

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 obtener más información, consulta gcloud eventarc providers describe

Sintaxis del patrón de ruta de acceso

La sintaxis del patrón de la ruta de acceso se define de la siguiente manera:

Sintaxis del patrón de ruta de acceso

Patrón /? Segment (/Segment)*
Segmento CaptureGroup | Expression
CaptureGroup { ID (= Expression)? }
Expresión Wildcard | MultiSegmentWildcard | NameSegment
NameSegment (Character* Wildcard? Character*)
ID [a-zA-Z0-9_]+
Comodín *
MultiSegmentWildcard **
Character1 [\\w\\s\\t~@#$%&.,?:;+='[]()-]

Leyenda:

? cero o uno
* cero o más
+ uno o más
| O
1 Solo se admiten los caracteres ASCII enumerados.

Expresiones

Una expresión puede ser de uno de los siguientes tipos de segmentos, y no puede estar vacía:

  • Un solo segmento Wildcard definido como * coincide con cero o más caracteres en el patrón.
  • Un MultiSegmentWildcard definido como ** coincide con cero o más segmentos del patrón.
  • Un NameSegment consiste en cero o un * y otros caracteres. Esta combinación te permite filtrar por prefijo, sufijo o extensión de archivo; por ejemplo, file-*.txt.

Ten en cuenta que una ruta de acceso puede contener muchos comodines de segmento único, pero solo un comodín de segmento múltiple. Por ejemplo, la siguiente ruta de acceso no es válida: /projects/**/buckets/**.

Regionalidad del recurso

Los nombres de los recursos pueden contener identificadores de ubicación. Por ejemplo:

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

Sin embargo, la coincidencia del patrón de la ruta de acceso está limitada por la regionalidad del recurso. Por ejemplo, para los activadores de registros de auditoría de Cloud, los comodines de ubicación solo coinciden con activadores de la región de registros de auditoría de Cloud o activadores globales.

Grupos de captura

Una CaptureGroup te permite capturar el contenido de una expresión. Para ello, asigna el valor a un nombre de variable entre llaves. por ejemplo, buckets/{path=**}/files/{filename=file-*.txt}. Un comodín de un solo segmento puede saltar =* en un grupo de captura, por ejemplo, /projects/_/buckets/{bucket}/objects/file.*

Formato de nombre de recurso

En la siguiente tabla, se proporcionan ejemplos de nombres de recursos completos para los servicios de Google Cloud más utilizados. No es una lista completa. Para obtener más información sobre el formato de los nombres de recursos completos, consulta la sección Nombres de recursos de la guía de diseño de la API.

Tipo de recurso Formato de nombre de recurso completo
Conjuntos de datos de BigQuery //bigquery.googleapis.com/projects/PROJECT_ID/datasets/DATASET_ID
Cuentas de Facturación de Cloud //cloudbilling.googleapis.com/billingAccounts/BILLING_ACCOUNT_ID
Servicios de Cloud Run //run.googleapis.com/projects/PROJECT_ID/locations/LOCATION_ID/services/SERVICE_ID
Instancias de Cloud SQL //sqladmin.googleapis.com/projects/PROJECT_ID/instances/INSTANCE_ID
Depósitos de Cloud Storage1 //storage.googleapis.com/projects/_/buckets/BUCKET_ID
Objetos de Cloud Storage 1, 2 //storage.googleapis.com/projects/_/buckets/BUCKET_ID/objects/OBJECT_ID
Instancias de Compute Engine //compute.googleapis.com/projects/PROJECT_ID/zones/ZONE/instances/INSTANCE_ID
Redes de Compute Engine //compute.googleapis.com/projects/PROJECT_ID/global/networks/NETWORK
Subredes de Compute Engine //compute.googleapis.com/projects/PROJECT_ID/regions/REGION/subnetworks/SUBNETWORK
Clústeres de Google Kubernetes Engine //container.googleapis.com/projects/PROJECT_ID/clusters/CLUSTER_ID
Servicio de app de App Engine de Identity-Aware Proxy //iap.googleapis.com/projects/PROJECT_NUMBER/iap_web/appengine-PROJECT_ID/services/APP_SERVICE_ID
Servicio de backend de Compute Engine de IAP //iap.googleapis.com/projects/PROJECT_NUMBER/iap_web/compute/services/BACKEND_SERVICE_ID_OR_NAME
Temas de Pub/Sub //pubsub.googleapis.com/projects/PROJECT_ID/topics/TOPIC_ID
Organizaciones de Resource Manager //cloudresourcemanager.googleapis.com/organizations/ORGANIZATION_NUMBER
Carpetas de Resource Manager //cloudresourcemanager.googleapis.com/folders/FOLDER_NUMBER
Proyectos de Resource Manager //cloudresourcemanager.googleapis.com/projects/PROJECT_ID

1 En Cloud Storage, los nombres de recursos contienen un guion bajo (_) en lugar de un ID del proyecto. No puedes reemplazar el guion bajo por un ID, nombre o número de proyecto.

2 Usa el nombre completo del objeto, incluidas las barras diagonales. En Cloud Storage, estos caracteres son parte del nombre del objeto, no separadores de ruta.

Ejemplos

Los siguientes ejemplos muestran cómo puedes y no puedes usar la sintaxis.

Patrones válidos

Patrón Descripción
/projects/project-1/datasets/dataset-1 Nombre del recurso específico.
/projects/project-1/regions/region-1/subnetworks/* Coincide con cualquier subred en project-1 y region-1.
/projects/_/buckets/bucket-1/objects/*.txt Coincide con todos los archivos TXT en el directorio.
/projects/_/buckets/bucket-1/objects/file-*.txt Coincide con todos los archivos TXT con el prefijo file- en el directorio.
/projects/project-1/serviceAccounts/service-account-email-1/keys/** Coincide con cualquier clave para un correo electrónico de cuenta de servicio específico.
/projects/_/**/file-*.txt Coincide con cualquier archivo TXT con el prefijo file- para todos los depósitos.
/projects/_/buckets/bucket-*/objects/file-*.txt Coincide con todos los archivos TXT con el prefijo file- para cualquier bucket con el prefijo bucket-.
/projects/_/buckets/{bucket}/objects/file.*
/projects/_/buckets/{bucket=*}/objects/file.*
/projects/_/buckets/*/objects/{filename=file.*} 		Tres representaciones diferentes del mismo filtro. Coincide con cualquier bucket con un archivo llamado file de cualquier tipo. Los dos primeros ejemplos también capturan el bucket y el último captura el nombre del archivo.
/projects/project-1/zones/zone-1/instances/** Coincide con cualquier ruta que se produzca en project-1 y zone-1.
/projects/*/zones/zone-1/instances/** Coincide con cualquier ruta zone-1 en cualquier proyecto.

Patrones no válidos

Patrón Descripción
/projects/_/buckets/bucket-1/objects/ Expresión vacía.
/projects//buckets/bucket-1/objects/file1.txt Expresión vacía.
/projects/_/buckets/bucket**/objects/file1.txt La expresión solo puede contener una *.
/projects/_/buckets/bucket-1/objects/file-*.* La expresión solo puede contener una *.
/projects/**/buckets/** La ruta de acceso del recurso solo puede contener un **.
/projects/_/buckets/{=*}/objects/file1.txt Falta el ID en el segmento.
/projects/_/buckets/{bucket=}/objects/file1.txt Expresión vacía dentro de un grupo de captura.
/projects/_/buckets/{bucket/objects/file1.txt El grupo de captura no está cerrado.

Coincidencia de patrones

Patrón Recurso ¿Hay coincidencias?
/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

¿Qué sigue?