경로 패턴 이해

Eventarc에서는 필터링할 때 경로 패턴을 적용할 수 있습니다. 경로 패턴 문법을 사용하면 이벤트와 일치하는 표현식을 정의할 수 있습니다. 이렇게 하면 만드는 Eventarc 트리거의 세부사항을 제어하고 특정 이벤트를 캡처하여 조치를 취할 수 있습니다. 예를 들어 특정 파일 변경과 같이 단일 이벤트에 적용되는 트리거를 만들거나 패턴 범위를 확장하고 더 광범위하게 적용되는 트리거를 만들 수 있습니다.

경로 패턴 적용

Eventarc Google Cloud 콘솔 페이지를 사용하거나 gcloud 명령어를 실행하면 트리거를 만들 때 경로 패턴을 적용하여 이벤트를 필터링할 수 있습니다.

예를 들어 리소스 이름 또는 데이터베이스 인스턴스(단일 인스턴스 또는 경로)를 필터링할 때 경로 패턴을 적용할 수 있습니다.

  • 리소스 이름 경로 패턴 지정은 Cloud 감사 로그 이벤트 및 resourceName 값에 대한 트리거를 만들 때 적용됩니다. 리소스 이름은 감사 로그를 통해 감사되는 리소스를 나타냅니다. 리소스 이름은 슬래시로 구분된 리소스 자체의 ID와 상위 리소스의 ID로 구성된 식별자를 통해 계층적으로 구성됩니다(예: /projects/project-1/datasets/dataset-id). Eventarc에서 수행한 필터링은 이러한 식별자 값을 기준으로 패턴을 일치시킵니다. 자세한 내용은 이 문서의 리소스 이름 형식을 참조하세요.

  • 데이터베이스 인스턴스 경로 패턴을 지정하면 Firebase 실시간 데이터베이스 패턴에 대한 트리거를 만들 때, 그리고 instance 또는 ref 값에 적용됩니다. 데이터베이스 인스턴스는 Firebase 실시간 데이터베이스 인스턴스를 나타냅니다. 데이터베이스 인스턴스의 인스턴스 이름 또는 해당 경로나 모든 하위 항목에서 데이터가 생성, 업데이트 또는 삭제될 때 이벤트를 수신할 문서 경로에 경로 패턴을 적용할 수 있습니다.

  • 리소스 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)*
Segment CaptureGroup | Expression
CaptureGroup { ID (= Expression)? }
Expression Wildcard | MultiSegmentWildcard | NameSegment
NameSegment (Character* Wildcard? Character*)
ID [a-zA-Z0-9_]+
Wildcard *
MultiSegmentWildcard **
Character1 [\\w\\s\\t~@#$%&.,?:;+='[]()-]

범례:

? 0 또는 1
* 0 이상
+ 1 이상
| OR
1 나열된 ASCII 문자만 지원됩니다.

표현식

표현식은 다음 세그먼트 유형 중 하나일 수 있으며 비워 둘 수 없습니다.

  • *로 정의된 단일 세그먼트 Wildcard는 패턴의 문자 0개 이상과 일치합니다.
  • **로 정의된 MultiSegmentWildcard는 패턴의 세그먼트 0개 이상과 일치합니다.
  • NameSegment는 * 0개나 1개 및 다른 문자로 구성됩니다. 이 조합을 사용하면 프리픽스, 서픽스 또는 파일 확장자를 기준으로 필터링할 수 있습니다(예: file-*.txt).

경로에는 다양한 단일 세그먼트 와일드 카드가 포함될 수 있지만 여러 세그먼트 와일드 카드 하나만 포함될 수 있습니다. 예를 들어 /projects/**/buckets/** 경로는 유효하지 않습니다.

리소스 리전성

리소스 이름에는 위치 식별자가 포함될 수 있습니다. 예를 들면 다음과 같습니다.

/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 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
IAP(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.*} 		동일한 필터의 3가지 표현. 모든 유형의 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

다음 단계