パスパターンについて

Eventarc では、フィルタリングでパスパターンを適用できます。パスパターン構文を使用すると、イベントを照合する式を定義できます。これにより、作成する Eventarc トリガーの粒度を制御し、特定のイベントをキャプチャして処理できます。たとえば、特定のファイルに対する変更など、単一のイベントに適用されるトリガーを作成できます。また、パターンの範囲を拡張して、より広範囲に適用されるトリガーを作成することもできます。

パスパターンを適用する

トリガーの作成時に、Eventarc Google Cloud コンソール ページを使用するか gcloud コマンドを実行することで、パスパターンを適用してイベントをフィルタリングできます。

たとえば、リソース名またはデータベース インスタンス（単一のインスタンスまたはパス）をフィルタリングするときに、パスパターンを適用できます。

  • リソース名のパスパターンは、Cloud Audit Logs イベントのトリガーを作成するときに、resourceName 値に指定します。リソース名は、監査ログを介して監査対象のリソースを示します。リソース名は、リソース自体の ID と親リソースの ID から構成される識別子を使用して、階層的に編成されます。/projects/project-1/datasets/dataset-id のように、これらの ID はすべてスラッシュで区切られています。Eventarc によるフィルタリングでは、これらの識別子の値に基づいてパターンが照合されます。詳細については、このドキュメントのリソース名の形式をご覧ください。

  • データベース インスタンスのパスパターンは、Firebase Realtime Database イベントのトリガーを作成するときに、instance または ref 値に指定します。データベース インスタンスは Firebase Realtime Database インスタンスを示します。パスパターンは、データベース インスタンスのインスタンス名に適用できます。また、パスまたはその子でデータの作成、更新、削除が発生したときにイベントを受信するドキュメント パスに適用することもできます。

  • リソース ID パスのパターンを指定すると、Cloud IoT イベントのトリガーの作成時に registry 値と device 値に適用されます。パスパターンを適用すると、ワイルドカード一致を使用して、レジストリの変更とレジストリ内のデバイスをフィルタリングできます。

詳しくは、特定のプロバイダ、イベントタイプ、宛先のトリガーを作成するをご覧ください。

パスパターンの適用可否を確認する

プロバイダからのイベントの属性にパスパターンを適用できるかどうかを確認するには、イベント プロバイダの説明を確認します。次に例を示します。

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
キャプチャ グループ { ID (= Expression)? }
eval Wildcard | MultiSegmentWildcard | NameSegment
NameSegment (Character* Wildcard? Character*)
ID [a-zA-Z0-9_]+
ワイルドカード *
MultiSegmentWildcard **
文字1 [\\w\\s\\t~@#$%&.,?:;+='[]()-]

凡例:

? 0 または 1
* 0 以上。
+ 1 以上
| OR
1 リストにある ASCII 文字のみがサポートされています。正規表現のマッチングはサポートされていません。サポートされているメタ文字:
  • \w は単語を指します。[a-zA-Z0-9_] とも表されます。
  • \t はタブを参照します
  • \s は空白文字を指します

式

式は、次のいずれかのセグメント タイプに設定できます。空白にすることはできません。

  • * として定義された単一セグメント Wildcard は、パターン内の 0 個以上の文字に一致します。
  • ** として定義された MultiSegmentWildcard は、パターン内の 0 個以上のセグメントに一致します。
  • NameSegment は、0 または 1 つの * と他の文字で構成されます。この組み合わせを使用すると、接頭辞、接尾辞、ファイル拡張子でフィルタリングできます。例: file-*.txt

1 つのパスに、1 つのセグメント ワイルドカードを複数含めることができますが、複数セグメントのワイルドカードは 1 つだけ使用できます。たとえば、パス /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 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 バケット2 //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 バケット内で、接頭辞が 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.*} 		同じフィルタの 3 つの表現。すべてのバケットを任意のタイプの file という名前のファイルと一致させます。最初の 2 つの例はバケットをキャプチャし、最後の例はファイル名をキャプチャします。
/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 式に含めることができる * は 1 つのみです。
/projects/_/buckets/bucket-1/objects/file-*.* 式に含めることができる * は 1 つのみです。
/projects/**/buckets/** リソースパスには ** を 1 つだけ含めることができます。
/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

次のステップ