Información sobre los patrones de ruta

Eventarc admite la aplicación de un patrón de ruta al filtrar. La sintaxis de patrón de ruta le permite definir una expresión que coincida con los eventos. De esta forma, puedes controlar la granularidad del activador de Eventarc que estás creando, así como capturar determinados eventos y tomar medidas al respecto. Por ejemplo, puedes crear un activador que se aplique a un solo evento, como un cambio en un archivo específico, o ampliar el alcance del patrón y crear un activador que se aplique de forma más general.

Aplicar un patrón de ruta

Puede aplicar un patrón de ruta para filtrar eventos al crear un activador mediante la página de la consola de Eventarc Google Cloud o ejecutando un comando gcloud.

Por ejemplo, puedes aplicar un patrón de ruta al filtrar por nombres de recursos o instancias de bases de datos (una sola instancia o una ruta).

  • Si se especifica un patrón de ruta de nombre de recurso, se aplica al crear un activador para eventos de registros de auditoría de Cloud y a los valores de resourceName. Un nombre de recurso indica el recurso que se está auditando a través de un registro de auditoría. Los nombres de los recursos se organizan de forma jerárquica mediante identificadores formados por el ID del recurso en sí y los IDs de los recursos superiores, todos ellos separados por barras diagonales, como en este ejemplo: /projects/project-1/datasets/dataset-id. El filtrado que realiza Eventarc coincide con patrones basados en los valores de estos identificadores. Para obtener más información, consulta la sección Formato del nombre de recurso de este documento.

  • Si especificas un patrón de ruta de instancia de base de datos, se aplicará al crear un activador para eventos de Firebase Realtime Database y a los valores de instance o ref. Una instancia de base de datos indica una instancia de Firebase Realtime Database. Puede aplicar un patrón de ruta al nombre de la instancia de la base de datos o a una ruta de documento para la que quiera recibir eventos cuando se creen, actualicen o eliminen datos en esa ruta o en cualquiera de sus elementos secundarios.

  • Si especifica un patrón de ruta de ID de recurso, se aplicará al crear un activador para eventos de Cloud IoT y a los valores de registry y device. Puede aplicar un patrón de ruta para filtrar los cambios en los registros y los dispositivos de un registro, con coincidencias comodín.

Para obtener más información, consulta las instrucciones para crear un activador para un proveedor, un tipo de evento y un destino específicos.

Identificar si puedes aplicar un patrón de ruta

Para confirmar si puede aplicar un patrón de ruta a un atributo de un evento de un proveedor, describa el proveedor del evento. Por ejemplo:

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

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

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

Por ejemplo:

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

La salida debería ser similar a la 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 de los patrones de ruta

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

Sintaxis de los patrones de ruta

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 **
Carácter1 [\\w\\s\\t~@#$%&.,?:;+='[]()-]

Leyenda:

? cero o uno
* Cero o más
+ uno o varios
| O
1 Solo se admiten los caracteres ASCII que se indican. No se admite la coincidencia de expresiones regulares. Metacaracteres admitidos:
  • \w hace referencia a una palabra. También se representa como [a-zA-Z0-9_].
  • \t hace referencia a una pestaña
  • \s hace referencia a un carácter de espacio en blanco

Expresiones

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

  • Un solo segmento Wildcard definido como * coincide con cero o más caracteres del patrón.
  • Un MultiSegmentWildcard definido como ** coincide con cero o más segmentos del patrón.
  • Un NameSegment consta de 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 puede contener muchos comodines de un solo segmento, pero solo un comodín de varios segmentos. Por ejemplo, la siguiente ruta no es válida: /projects/**/buckets/**.

Regionalidad de los recursos

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

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

Sin embargo, la coincidencia de patrones de ruta está limitada por la regionalidad de los recursos. Por ejemplo, en el caso de los activadores de registros de auditoría de Cloud, las comodines de ubicación solo coinciden con los activadores de la región de registros de auditoría de Cloud o con los activadores globales.

Grupos de captura

Un 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 segmento único puede omitir =* en un grupo de captura. Por ejemplo, /projects/_/buckets/{bucket}/objects/file.*

Formato de nombres de recursos

En la siguiente tabla se muestran ejemplos de nombres de recursos completos de servicios que se usan con frecuencia.Google Cloud Esta lista no es exhaustiva. 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 APIs.

Tipo de recurso Formato de nombre completo de recurso
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
Los documentos1 de Cloud Firestore //firestore.googleapis.com/projects/PROJECT_ID/databases/DATABASE_ID/documents/DOCUMENT
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
buckets de Cloud Storage2 //storage.googleapis.com/projects/_/buckets/BUCKET_ID
Objetos2, 3 de Cloud Storage //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
Clusters de Google Kubernetes Engine //container.googleapis.com/projects/PROJECT_ID/clusters/CLUSTER_ID
Servicio de aplicación de App Engine de Identity-Aware Proxy //iap.googleapis.com/projects/PROJECT_NUMBER/iap_web/appengine-PROJECT_ID/services/APP_SERVICE_ID
Servicio 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 Firestore, no especifiques una barra inicial al crear un activador (consulta los ejemplos). Para obtener más información, consulta el artículo sobre el modelo de datos de Cloud Firestore.

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

3 En Cloud Storage, usa el nombre completo del objeto, incluidas las barras diagonales. Estos caracteres forman parte del nombre del objeto, no son separadores de ruta.

Ejemplos

En los siguientes ejemplos se muestra cómo se puede y cómo no se puede usar la sintaxis.

Patrones válidos

Patrón Descripción
/projects/project-1/datasets/dataset-1 Nombre de recurso específico.
/projects/project-1/regions/region-1/subnetworks/* Coincide con cualquier subred de project-1 y region-1.
/projects/_/buckets/bucket-1/objects/*.txt Coincide con todos los archivos TXT del contenedor.
/projects/_/buckets/bucket-1/objects/file-*.txt Coincide con todos los archivos TXT con el prefijo file- del contenedor.
/projects/project-1/serviceAccounts/service-account-email-1/keys/** Coincide con cualquier clave de una dirección de correo de una cuenta de servicio específica.
/projects/_/**/file-*.txt Coincide con cualquier archivo TXT con el prefijo file- de todos los contenedores.
/projects/_/buckets/bucket-*/objects/file-*.txt Coincide con todos los archivos TXT con el prefijo file- de cualquier contenedor 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 contenedor con un archivo llamado file de cualquier tipo. Los dos primeros ejemplos también capturan el segmento y el último ejemplo captura el nombre del archivo.
/projects/project-1/zones/zone-1/instances/** Coincide con cualquier elemento de project-1 y zone-1.
/projects/*/zones/zone-1/instances/** Coincide con cualquier elemento de 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 un elemento *.
/projects/_/buckets/bucket-1/objects/file-*.* La expresión solo puede contener un elemento *.
/projects/**/buckets/** La ruta 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 se ha cerrado.

Coincidencia de patrones

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

Siguientes pasos