스토리지 일괄 작업의 CEL 필터 참조

이 페이지에서는 Storage Insights 데이터 세트 필드를 기반으로 스토리지 일괄 작업 작업의 고급 필터를 구성할 때 지원되는 Common Expression Language (CEL) 구문 및 작업을 설명합니다.

고급 필터를 사용하면 Storage Insights 데이터 세트의 필드를 기반으로 수백만 개의 파일에서 조건을 평가하고 관리 작업을 자동화할 수 있습니다. 지원되는 필터는 CEL 규칙을 객체 메타데이터에 직접 사용합니다.

작업을 만들 때 Google Cloud CLI에서 --bucket-filters 및 --object-filters 플래그를 사용하거나 JSON API에서 bucketFilters 및 objectFilters 필드를 사용하여 필터 규칙을 제공합니다. 이 옵션을 사용하면 BigQuery를 수동으로 쿼리하고, 객체 목록을 CSV로 내보내고, 매니페스트를 버킷에 다시 업로드할 필요가 없습니다. 객체 선택에 데이터 세트 필터를 사용하면 스토리지 일괄 작업은 선택한 데이터 세트 스냅샷을 기준으로 현재 활성 상태인 객체를 타겟팅합니다. 따라서 작업에는 스냅샷 시점에 softDeleteTime 및 timeDeleted 모두에 NULL 값이 있는 객체만 포함됩니다.

지원되는 연산자 및 함수

고급 필터는 논리적 AND (&&) 문으로 결합된 조건을 지원합니다. 다음 연산자를 사용하여 기준 문자열을 빌드합니다.

연산자 CEL 사용 동일한 GoogleSQL 구문 설명
StartsWith name.startsWith("prefix") STARTS_WITH(name, "prefix") 특정 프리픽스로 시작하는 문자열 속성이 있는 객체를 일치시킵니다.
EndsWith name.endsWith(".pdf") ENDS_WITH(name, ".pdf") 특정 서픽스로 끝나는 문자열 속성이 있는 객체를 일치시킵니다.
같음 == = 특정 값과 동일한 속성이 있는 객체를 일치시킵니다.
같지 않음 != != 특정 값과 정확히 일치하는 속성이 있는 객체를 제외합니다.
초과 > > 기준점을 초과하는 정수 또는 타임스탬프 속성이 있는 객체를 일치시킵니다.
이상 >= >= 기준점과 같거나 초과하는 정수 또는 타임스탬프 속성이 있는 객체를 일치시킵니다.
미만 < < 기준점 미만의 정수 또는 타임스탬프 속성이 있는 객체를 일치시킵니다.
이하 <= <= 기준점과 같거나 미만의 정수 또는 타임스탬프 속성이 있는 객체를 일치시킵니다.
포함 name.contains("substring") STRPOS(name, "substring") != 0 하위 문자열이 포함된 문자열 속성이 있는 객체를 일치시킵니다.
In name in ['a', 'b'] name IN UNNEST(ARRAY<STRING>['a', 'b']) 제공된 목록에 있는 속성이 있는 객체를 일치시킵니다.
논리 부정 ! NOT 조건과 일치하지 않는 객체를 필터링하도록 규칙을 반전합니다.
타임스탬프 timestamp("2025-01-01T00:00:00Z") TIMESTAMP "2025-01-01 00:00:00 UTC" RFC 3339 형식으로 지정된 날짜 문자열을 타임스탬프로 변환합니다. 이 함수는 BigQuery TIMESTAMP 유형 표준과 일치하도록 마이크로초 정밀도를 지원합니다.
존재 contexts.exists(c, c.key == "env") EXISTS(SELECT c FROM UNNEST(contexts) AS c WHERE c.key = "env" LIMIT 1) 반복 레코드 유형 속성 내에서 하나 이상의 항목이 특정 조건을 충족하는 객체를 일치시킵니다.

지원되는 식별자

필터 표현식을 구성할 때 버킷 수준 필드와 객체 수준 필드를 모두 참조할 수 있습니다. 다음 식별자는 Storage Insights 데이터 세트 테이블 스키마의 인식된 필드에 매핑됩니다.

버킷 속성

다음 버킷 수준 필드를 사용하여 스토리지 일괄 작업 작업에 포함할 버킷을 필터링할 수 있습니다.

필드 유형 설명
name STRING 버킷의 이름입니다.
autoclass RECORD enabled 및 toggleTime 메타데이터가 포함됩니다.
autoclass.enabled 부울 버킷에 자동 클래스가 사용 설정되어 있는지 나타냅니다.
autoclass.toggleTime TIMESTAMP 자동 클래스가 마지막으로 사용 설정 또는 중지된 시간입니다.
labels 반복 레코드 표준 키-값 맵이 포함됩니다.
location STRING 버킷 위치 식별자입니다.
softDeletePolicy RECORD retentionDurationSeconds 및 effectiveTime이 포함됩니다.
softDeletePolicy.retentionDurationSeconds INTEGER 소프트 삭제 보관 기간(초)입니다.
softDeletePolicy.effectiveTime TIMESTAMP 소프트 삭제 정책이 적용된 시간입니다.

객체 속성

다음 속성을 사용하여 객체 수준 필드를 기준으로 스토리지 일괄 작업 작업을 필터링할 수 있습니다.

필드 유형 설명
name STRING 객체 이름입니다.
contexts 반복 레코드 객체에 연결된 컨텍스트입니다.
contexts.key STRING 커스텀 컨텍스트 키입니다.
contexts.value STRING 커스텀 컨텍스트 키의 값입니다.
contexts.type STRING 커스텀 컨텍스트 유형입니다.
contexts.createTime TIMESTAMP 커스텀 컨텍스트 키가 생성된 시간입니다.
contexts.updateTime TIMESTAMP 커스텀 컨텍스트 키가 업데이트된 시간입니다.
contentType STRING MIME 유형 콘텐츠 분류입니다.
customTime TIMESTAMP 사용자 정의 타임스탬프입니다.
generation INTEGER 객체 생성 식별자입니다.
metadata 반복 레코드 커스텀 메타데이터입니다.
metadata.key STRING 커스텀 메타데이터 키입니다.
metadata.value STRING 커스텀 메타데이터 값입니다.
metageneration INTEGER 메타데이터 생성 식별자입니다.
retentionExpirationTime TIMESTAMP 객체 보관이 만료되는 시간입니다.
securityInsights RECORD 객체의 공개 액세스 통계가 포함됩니다.
securityInsights.publicAccessInsight RECORD 객체의 공개 액세스 가능 상태를 제공합니다.
securityInsights.publicAccessInsight.readPublicAccess STRING 객체의 공개 읽기 가능 상태입니다. 지원되는 값은 PUBLIC, NOT_PUBLIC, UNSUPPORTED, ERROR입니다.
securityInsights.publicAccessInsight.readPublicAccessSource STRING readPublicAccess가 PUBLIC이면 공개 읽기 권한의 소스를 반환합니다. 지원되는 값은 Object, Bucket, ERROR입니다.
securityInsights.publicAccessInsight.writePublicAccess STRING 객체의 공개 쓰기 가능 상태입니다. 지원되는 값은 PUBLIC, NOT_PUBLIC, UNSUPPORTED, ERROR입니다.
size INTEGER 객체 크기(바이트)입니다.
storageClass STRING 할당된 스토리지 클래스입니다.
temporaryHold 부울 출시를 방지하는 활성 차단 상태입니다.
timeCreated TIMESTAMP 최초 생성 등록 시계입니다.
timeStorageClassUpdated TIMESTAMP 스토리지 클래스가 마지막으로 업데이트된 시간입니다.
updated TIMESTAMP 객체가 마지막으로 업데이트된 시간입니다.

표현식 형식 규칙

작업을 대규모로 실행할 수 있도록 쿼리 엔진은 다음 형식 규칙을 적용합니다.

  1. 필터 조건: 논리적 AND (&&) 연산자만 사용하여 필터 조건을 결합할 수 있습니다. 쿼리 엔진은 논리적 OR(||) 연산자를 지원하지 않습니다.
  2. 인수 위치 지정: 대상 메타데이터 필드를 함수의 왼쪽에 배치해야 합니다. 예를 들어 "live-".startsWith(name) 대신 name.startsWith("live-")을 사용합니다.
  3. 배열 메서드: exists 매크로를 반복 필드에서 직접 호출할 수 있습니다. 예를 들어 contexts.exists(...) 또는 metadata.exists(...)와 같습니다.
  4. 버킷 한도: 단일 스토리지 일괄 작업은 최대 1,000개의 버킷에서 작동할 수 있습니다. 필터 표현식이 데이터 세트에서 1,000개가 넘는 버킷과 동적으로 일치하면 작업 생성이 실패합니다. 특정 버킷 수준 필드(예: 위치 필터링(예: location == "us-central1") 또는 이름 일치(예: name.startsWith("prod-")))를 사용하여 쿼리 범위를 좁히고 이 한도를 충족합니다.
  5. 글자 수 제한: 버킷 필터와 객체 필터는 각각 최대 150자로 제한됩니다.

예시

다음 예에서는 리소스를 프로젝트 전체에서 타겟팅하는 데 사용할 수 있는 일반적인 결합된 필터를 보여줍니다. gcloud storage batch-operations jobs create 명령어에서 필터 스니펫을 플래그로 직접 지정합니다.

  • 특정 버킷 타겟팅: 특정 버킷의 객체에 작업을 적용합니다. 

    --bucket-filters="name in ['bucket-1', 'bucket-2']"

  • 스토리지 클래스 및 버킷 위치 확인: US 위치의 Standard Storage 스토리지 클래스에 있는 객체에 작업을 적용합니다. 

    --bucket-filters="location.startsWith('us')" 
    
--object-filters="storageClass == 'STANDARD'"

  • 소프트 삭제 보관으로 필터링: 소프트 삭제가 7일 이상 사용 설정된 버킷의 객체에 작업을 적용합니다. 

    --bucket-filters="softDeletePolicy.retentionDurationSeconds >= 604800"

  • 객체 크기 및 확장 프로그램으로 필터링: 5 KiB보다 큰 PDF 객체를 찾습니다. 

    --object-filters="size >= 5120 && name.endsWith('.pdf')"

  • 커스텀 컨텍스트 키 확인: 커스텀 컨텍스트 키 env가 있는 객체에 작업을 적용합니다. 

    --object-filters="contexts.exists(context, context.key == 'env')"

  • 커스텀 컨텍스트 키-값 쌍 일치: 값이 prod인 커스텀 컨텍스트 키 env가 있는 객체에 작업을 적용합니다. 

    --object-filters="contexts.exists(context, context.key == 'env' && context.value == 'prod')"

  • 프리픽스 및 서픽스로 커스텀 컨텍스트 값 일치: 프리픽스 prod로 시작하고 서픽스 .txt로 끝나는 커스텀 컨텍스트 값이 있는 객체에 작업을 적용합니다. 

    --object-filters="contexts.exists(context, context.value.startsWith('prod') && context.value.endsWith('.txt'))"

  • 누락된 컨텍스트 키 식별: 커스텀 컨텍스트 키 env가 없는 객체에 작업을 적용합니다. 

    --object-filters="!contexts.exists(context, context.key == 'env')"

다음 단계