パスパターンについて

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

パスパターンを適用する

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

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

リソース名のパスパターンは、Cloud Audit Logs イベントのトリガーを作成するときに、resourceName 値に指定します。リソース名は、監査ログを介して監査対象のリソースを示します。リソース名は、リソース自体の ID と親リソースの ID から構成される識別子を使用して、階層的に編成されます。/projects/_/buckets/bucket-id/objects/object-id のように、これらの ID はすべてスラッシュで区切られています。Eventarc によるフィルタリングでは、これらの識別子の値に基づいてパターンが照合されます。詳細については、リソース名をご覧ください。
データベースインスタンスのパスパターンは、Firebase Realtime Database イベントのトリガーを作成するときに、instance または ref 値に指定します。データベースインスタンスは Firebase Realtime Database インスタンスを示します。パスパターンは、データベースインスタンスのインスタンス名に適用できます。また、パスまたはその子でデータの作成、更新、削除が発生したときにイベントを受信するドキュメントパスに適用することもできます。
リソース ID パスのパターンを指定すると、Cloud IoT イベントのトリガーの作成時に registry 値と device 値に適用されます。パスパターンを適用すると、ワイルドカード一致を使用して、レジストリの変更とレジストリ内のデバイスをフィルタリングできます。

詳細については、Google Cloud コンソールでトリガーを作成するまたは gcloud CLI を使用してトリガーを作成するをご覧ください。

パスパターンを適用できるかどうかを確認する

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

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

凡例:

`?`	0 または 1
`*`	0 以上。
`+`	1 以上
`\|`	OR

¹ リストにある ASCII 文字のみがサポートされています。

式

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

* として定義された単一セグメント 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.*）。

例

次の例は、この構文を使用できる場合と使用できない場合を示しています。

有効なパターン

パターン	説明
`/projects/_/buckets/bucket-1/objects/file1.txt`	特定のリソース名。
`/projects/_/buckets/bucket-1/objects/*`	バケット内の任意のファイルと一致します。
`/projects/_/buckets/bucket-1/objects/*.txt`	バケット内のすべての TXT ファイルと一致します。
`/projects/_/buckets/bucket-1/objects/file-*.txt`	バケット内で、接頭辞が `file-` のすべての TXT ファイルと一致します。
`/projects/_/buckets/bucket-1/objects/**`	バケット内のすべてのものと一致します。
`/projects/_/buckets/bucket-1/objects/files/*`	`bucket-1` バケットの `files` ディレクトリ内の任意のファイルと一致します。
`/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/_/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/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/*.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`

次のステップ

Eventarc でサポートされているイベントのリストについては、Eventarc でサポートされているイベントタイプをご覧ください。