瞭解路徑模式

Eventarc 支援在篩選時套用路徑模式。路徑模式語法可讓您定義與事件相符的運算式。這可讓您控制要建立的 Eventarc 觸發條件精細程度，並擷取特定事件及對事件採取行動。舉例來說，您可以建立適用於單一事件的觸發條件，例如特定檔案的變更，也可以擴大模式的範圍，建立適用於更廣泛範圍的觸發條件。

套用路徑模式

使用 Eventarc Google Cloud 控制台頁面建立觸發條件，或執行 gcloud 指令時，可以套用路徑模式來篩選事件。

舉例來說，篩選資源名稱或資料庫執行個體 (單一執行個體或路徑) 時，可以套用路徑模式。

  • 建立 Cloud 稽核記錄事件的觸發條件時，以及 resourceName 值時，請指定資源名稱路徑模式。資源名稱會指出透過稽核記錄稽核的資源。資源名稱是由資源本身的 ID 和任何父項資源的 ID 組成，並以正斜線分隔，形成階層式結構，例如：/projects/project-1/datasets/dataset-id。Eventarc 執行的篩選作業會根據這些 ID 的值比對模式。詳情請參閱本文的「資源名稱格式」。

  • 建立 Firebase 即時資料庫事件的觸發程序時，以及針對 instance 或 ref 值，請指定資料庫執行個體路徑模式。資料庫執行個體是指 Firebase 即時資料庫執行個體。您可以將路徑模式套用至資料庫執行個體的執行個體名稱，或要接收事件的文件路徑 (當該路徑或任何子項中的資料建立、更新或刪除時)。

  • 建立 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)*
區隔 CaptureGroup | Expression
CaptureGroup { ID (= Expression)? }
Expression Wildcard | MultiSegmentWildcard | NameSegment
NameSegment (Character* Wildcard? Character*)
ID [a-zA-Z0-9_]+
萬用字元 *
MultiSegmentWildcard **
角色1 [\\w\\s\\t~@#$%&.,?:;+='[]()-]

圖例：

? 零或一
* 零或更多
+ 一或多個
| 或
1 系統僅支援所列的 ASCII 字元。 系統不支援規則運算式比對。支援的中繼字元：
  • \w 是指字詞，也表示為 [a-zA-Z0-9_]
  • \t 是指分頁
  • \s 是指空白字元

運算式

運算式可以是下列任一區隔類型，且不得為空白：

  • 定義為 * 的單一區段 Wildcard 會比對模式中的零個以上字元。
  • 定義為 ** 的 MultiSegmentWildcard 會比對模式中的零或多個區隔。
  • NameSegment 包含零或一個 * 和其他字元。您可以使用這組組合依前置字串、後置字串或副檔名篩選，例如 file-*.txt。

請注意，路徑可以包含多個單一段落萬用字元，但只能有一個多段落萬用字元。舉例來說，以下路徑無效： /projects/**/buckets/**。

資源區域性

資源名稱可包含位置 ID。例如：

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

不過，路徑模式比對會受到資源區域性的限制。舉例來說，如果是 Cloud 稽核記錄觸發條件，位置萬用字元只會比對 Cloud 稽核記錄區域或全域觸發條件的觸發條件。

擷取群組

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 Firestore 文件1 //firestore.googleapis.com/projects/PROJECT_ID/databases/DATABASE_ID/documents/DOCUMENT
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 buckets2 //storage.googleapis.com/projects/_/buckets/BUCKET_ID
Cloud Storage 物件2、3 //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 Firestore 觸發程序時，請勿指定開頭斜線 (請參閱範例)。詳情請參閱 Cloud Firestore 資料模型。

2 對於 Cloud Storage，資源名稱包含底線 (_)，而非專案 ID。您無法將底線替換為專案 ID、專案名稱或專案編號。

3 如果是 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 比對 bucket 中所有前置字串為 file- 的 TXT 檔案。
/projects/project-1/serviceAccounts/service-account-email-1/keys/** 比對特定服務帳戶電子郵件地址的任何金鑰。
/projects/_/**/file-*.txt 與所有 bucket 中前置字串為 file- 的 TXT 檔案相符。
/projects/_/buckets/bucket-*/objects/file-*.txt 符合前置字串為 file- 的所有 TXT 檔案，適用於前置字串為 bucket- 的任何 bucket。
/projects/_/buckets/{bucket}/objects/file.*
/projects/_/buckets/{bucket=*}/objects/file.*
/projects/_/buckets/*/objects/{filename=file.*} 		同一篩選條件的三種不同表示法。比對任何含有名為 file 的檔案 (任何類型) 的 bucket。前兩個範例也會擷取 bucket，最後一個範例則會擷取檔案名稱。
/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
{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

後續步驟