了解路径模式

Eventarc 支持在过滤时应用路径模式。路径模式语法允许您定义与事件匹配的表达式。这样，您就可以控制正在创建的 Eventarc 触发器的粒度，捕获某些事件并对其执行操作。例如，您可以创建一个适用于单个事件的触发器（例如对特定文件的更改），也可以扩展模式的范围并创建更广泛适用的触发器。

应用路径模式

您可以在使用 Eventarc Google Cloud 控制台页面或通过运行 gcloud 命令来创建触发器时应用路径模式来过滤事件。

例如，在过滤资源名称或数据库实例（单个实例或路径）时，可以应用路径模式。

  • 为 Cloud Audit Logs 事件和 resourceName 值创建触发器时，可以指定资源名称路径模式。资源名称表示通过审核日志进行审核的资源。资源名称使用标识符按层级进行排列，标识符由资源本身的 ID 和任何父资源的 ID 组成，所有 ID 使用正斜杠分隔，例如：/projects/project-1/datasets/dataset-id。Eventarc 所执行的过滤会根据这些标识符的值来匹配模式。如需了解详情，请参阅本文档中的资源名称格式。

  • 为 Firebase Realtime Database 事件以及 instance 或 ref 值创建触发器时，可以指定数据库实例路径模式。数据库实例表示 Firebase Realtime Database 实例。您可以将路径模式应用于对数据库实例的实例名称，也可以应用于要在该路径或其任何子路径中创建、更新或删除数据时接收其事件的文档路径。

  • 为 Cloud IoT 事件以及 registry 和 device 值创建触发器时，可以指定资源 ID 路径模式。您可以借助通配符匹配，应用路径模式来过滤注册表中的更改和注册表中的设备。

如需了解详情，请参阅为特定提供方、事件类型和目的地创建触发器的说明。

确定是否可以应用路径模式

如需确认您是否可将路径模式应用于提供方的事件属性，请描述事件提供方。例如：

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

输出类似于以下内容，pathPatternSupported 值为 true 表示您可以应用路径模式：

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

或者，例如：

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

其中输出类似于以下内容：

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

如需了解详情，请参阅 gcloud eventarc providers describe。

路径模式语法

路径模式语法的定义如下：

路径模式语法

模式 /? Segment (/Segment)*
Segment CaptureGroup | Expression
CaptureGroup { ID (= Expression)? }
表达式 Wildcard | MultiSegmentWildcard | NameSegment
NameSegment (Character* Wildcard? Character*)
ID [a-zA-Z0-9_]+
通配符 *
MultiSegmentWildcard **
字符1 [\\w\\s\\t~@#$%&.,?:;+='[]()-]

图例：

? 零或一
* 零个或多个
+ 一个或多个
| 或
1 仅支持列出的 ASCII 字符。

表达式

表达式可以是以下片段类型之一，且不能为空：

  • 定义为 * 的单个分段 Wildcard 与模式中的零个或多个字符匹配。
  • 定义为 ** 的 MultiSegmentWildcard 与模式中的零个或多个分段匹配。
  • NameSegment由零个或一个 * 和其他字符组成。这种组合允许您按前缀、后缀或文件扩展名进行过滤；例如 file-*.txt。

请注意，一个路径可以包含许多单段通配符，但只能包含一个多段通配符。例如，以下路径无效：/projects/**/buckets/**。

资源区域性

资源名称可以包含位置标识符。例如：

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

但是，路径模式匹配受资源区域性限制。例如，对于 Cloud Audit Logs 触发器，位置通配符仅匹配来自 Cloud Audit Logs 区域的触发器或全局触发器。

捕获组

CaptureGroup 允许您捕获表达式的内容。为此，您可以将值分配给大括号中的变量名称；例如 buckets/{path=**}/files/{filename=file-*.txt}。单段通配符可以省略捕获组中的 =*；例如 /projects/_/buckets/{bucket}/objects/file.*

资源名称格式

下表提供了常用 Google Cloud 服务的完整资源名称示例。但这并非完整列表。如需详细了解完整资源名称的格式，请参阅 API 设计指南的资源名称部分。

资源类型 完整资源名称格式
BigQuery 数据集 //bigquery.googleapis.com/projects/PROJECT_ID/datasets/DATASET_ID
Cloud Billing 账号 //cloudbilling.googleapis.com/billingAccounts/BILLING_ACCOUNT_ID
Cloud Run 服务 //run.googleapis.com/projects/PROJECT_ID/locations/LOCATION_ID/services/SERVICE_ID
Cloud SQL 实例 //sqladmin.googleapis.com/projects/PROJECT_ID/instances/INSTANCE_ID
Cloud Storage 存储桶1 //storage.googleapis.com/projects/_/buckets/BUCKET_ID
Cloud Storage 对象1、2 //storage.googleapis.com/projects/_/buckets/BUCKET_ID/objects/OBJECT_ID
Compute Engine 实例 //compute.googleapis.com/projects/PROJECT_ID/zones/ZONE/instances/INSTANCE_ID
Compute Engine 网络 //compute.googleapis.com/projects/PROJECT_ID/global/networks/NETWORK
Compute Engine 子网 //compute.googleapis.com/projects/PROJECT_ID/regions/REGION/subnetworks/SUBNETWORK
Google Kubernetes Engine 集群 //container.googleapis.com/projects/PROJECT_ID/clusters/CLUSTER_ID
Identity-Aware Proxy App Engine 应用服务 //iap.googleapis.com/projects/PROJECT_NUMBER/iap_web/appengine-PROJECT_ID/services/APP_SERVICE_ID
IAP Compute Engine 后端服务 //iap.googleapis.com/projects/PROJECT_NUMBER/iap_web/compute/services/BACKEND_SERVICE_ID_OR_NAME
Pub/Sub 主题 //pubsub.googleapis.com/projects/PROJECT_ID/topics/TOPIC_ID
Resource Manager 组织 //cloudresourcemanager.googleapis.com/organizations/ORGANIZATION_NUMBER
Resource Manager 文件夹 //cloudresourcemanager.googleapis.com/folders/FOLDER_NUMBER
Resource Manager 项目 //cloudresourcemanager.googleapis.com/projects/PROJECT_ID

1 对于 Cloud Storage，资源名称包含下划线 (_)，而不是项目 ID。您不能将下划线替换为项目 ID、项目名称或项目编号。

2 使用完整的对象名称，包括正斜杠。在 Cloud Storage 中，这些字符是对象名称的一部分，而不是路径分隔符。

示例

以下示例演示了在什么情况下可以和不可以使用语法。

有效模式

模式 说明
/projects/project-1/datasets/dataset-1 特定资源名称。
/projects/project-1/regions/region-1/subnetworks/* 匹配 project-1 和 region-1 中的任何子网。
/projects/_/buckets/bucket-1/objects/*.txt 匹配存储桶中的所有 TXT 文件。
/projects/_/buckets/bucket-1/objects/file-*.txt 匹配存储桶中所有前缀为 file- 的 TXT 文件。
/projects/project-1/serviceAccounts/service-account-email-1/keys/** 匹配特定服务账号电子邮件地址的任何密钥。
/projects/_/**/file-*.txt 匹配所有存储桶的前缀为 file- 的 TXT 文件。
/projects/_/buckets/bucket-*/objects/file-*.txt 匹配前缀为 bucket- 的任何存储桶的前缀为 file- 的所有 TXT 文件。
/projects/_/buckets/{bucket}/objects/file.*
/projects/_/buckets/{bucket=*}/objects/file.*
/projects/_/buckets/*/objects/{filename=file.*} 		同一过滤条件的三种不同表示法。匹配包含名为 file 的任意类型文件的任何存储桶。前两个示例还会捕获存储桶，最后一个示例则捕获文件名。
/projects/project-1/zones/zone-1/instances/** 匹配 project-1 和 zone-1 中的任何内容。
/projects/*/zones/zone-1/instances/** 匹配任何项目中 zone-1 的任何内容。

无效格式

模式 说明
/projects/_/buckets/bucket-1/objects/ 空表达式。
/projects//buckets/bucket-1/objects/file1.txt 空表达式。
/projects/_/buckets/bucket**/objects/file1.txt 表达式只能包含一个 *。
/projects/_/buckets/bucket-1/objects/file-*.* 表达式只能包含一个 *。
/projects/**/buckets/** 资源路径只能包含一个 **。
/projects/_/buckets/{=*}/objects/file1.txt 分段中缺少 ID。
/projects/_/buckets/{bucket=}/objects/file1.txt 捕获组中的空表达式。
/projects/_/buckets/{bucket/objects/file1.txt 捕获组未关闭。

模式匹配

模式 资源 匹配？
/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

后续步骤