프리픽스별 필터링

이 가이드에서는 포함 및 제외 프리픽스를 사용하여 전송되는 파일을 제어하는 방법을 설명합니다.

개요

Storage Transfer Service를 사용하면 프리픽스를 사용하여 Amazon S3, Microsoft Azure Blob Storage, Cloud Storage 소스의 데이터를 필터링할 수 있습니다. 접두사는 객체 집합을 지정하는 경로의 시작 부분에 있는 문자열입니다.

접두사 필터는 다음 세 가지 방법으로 사용할 수 있습니다.

• 프리픽스 포함: 지정된 프리픽스와 일치하는 객체만 전송됩니다.

• 프리픽스 제외: 지정된 프리픽스와 일치하는 객체는 전송에서 제외됩니다.

• 둘 다 함께: 포함 및 제외 프리픽스를 동시에 사용하여 보다 세부적으로 제어할 수 있습니다. 함께 사용하는 경우 모든 제외 프리픽스는 지정된 포함 프리픽스 중 하나로 시작해야 합니다.

접두사를 지정하지 않으면 소스 버킷의 모든 객체가 전송됩니다.

규칙

접두사에는 다음 규칙이 적용됩니다.

• 선행 슬래시 없음: 프리픽스에 선행 슬래시를 포함하지 마세요. s3://my-bucket/logs/2025/requests.gz 경로의 경우 올바른 접두사는 logs/2025/requests.gz입니다.

• 부분 일치: 접두사는 부분 일치를 통해 작동합니다. 예를 들어 path 접두사는 path_1/ 및 path_2/와 모두 일치합니다.

• 와일드 카드 없음: 와일드 카드는 지원되지 않습니다.

• 소스 폴더 기준: 전송 소스가 특정 폴더인 경우 접두사는 해당 폴더를 기준으로 평가됩니다. gs://my-bucket/data/ 소스의 경우 reports 포함 접두사는 gs://my-bucket/data/reports 아래의 모든 파일과 일치합니다.

• 고유한 포함 프리픽스: 각 포함 프리픽스는 객체 네임스페이스의 고유한 부분을 정의해야 합니다. 이미 다른 포함 프리픽스로 처리된 포함 프리픽스는 사용할 수 없습니다. 예를 들어 data/ 및 data/reports/를 모두 포함 프리픽스로 지정할 수 없습니다.

• 제외 프리픽스 종속 항목: 포함 프리픽스와 제외 프리픽스를 함께 사용하는 경우 모든 제외 프리픽스는 지정된 포함 프리픽스 중 하나로 시작해야 합니다. 예를 들어 path가 포함 프리픽스인 경우 유효한 제외 프리픽스는 path/b 또는 pathway일 수 있습니다. 제외 접두사만 사용하는 경우에는 이 규칙이 적용되지 않습니다.

• 최대 1,000개의 접두사: 단일 전송 작업은 최대 1,000개의 접두사를 지원합니다. 추가 접두사가 필요한 경우 전송을 여러 작업으로 분할할 수 있습니다.

더 일반적인 프리픽스 정보는 Amazon S3 문서의 프리픽스와 구분자를 사용하여 계층적 구조로 키 나열 또는 Cloud Storage의 Objects list 메서드를 참고하세요.

프리픽스 지정 방법

Cloud 콘솔

Cloud 콘솔을 사용하여 포함 및 제외 프리픽스를 지정하려면 새 전송을 만들 때 또는 기존 전송을 업데이트할 때 값을 입력합니다.

gcloud CLI

gcloud CLI를 사용하여 포함 및 제외 프리픽스를 지정하려면 gcloud transfer jobs create 명령어 또는 gcloud transfer jobs update 명령어에 --include-prefixes 및 --exclude-prefixes 플래그를 전달합니다.

gcloud transfer jobs create SOURCE DESTINATION \
  --include-prefixes="path_1/,path_2/" --exclude-prefixes="path_1/subpath_2/"

여러 프리픽스를 쉼표로 구분하고 쉼표 뒤에 공백을 생략합니다. 예를 들면 --include-prefixes="foo,bar"입니다.

REST

REST API를 사용하여 포함 및 제외 프리픽스를 지정하려면 includePrefixes[] 및 excludePrefixes[] 필드를 사용합니다.

{
    "description": "YOUR DESCRIPTION",
    "status": "ENABLED",
    "projectId": "PROJECT_ID",
    "schedule": {
        "scheduleStartDate": {
            "day": 1,
            "month": 1,
            "year": 2015
        },
        "startTimeOfDay": {
            "hours": 1,
            "minutes": 1
        }
    },
    "transferSpec": {
        "gcsDataSource": {
            "bucketName": "GCS_SOURCE_NAME"
        },
        "gcsDataSink": {
            "bucketName": "GCS_SINK_NAME"
        },
        "transferOptions": {
            "deleteObjectsFromSourceAfterTransfer": true
        },
        "objectConditions": {
            "includePrefixes": [
                "path_1/",
                "path_2/"
            ],
            "excludePrefixes": [
                "path_1/subpath_2/object_5"
            ]
        }
    }
}

자세한 내용은 ObjectConditions 참조를 확인하세요.

객체 및 경로 예시

다음 예시에서는 이 샘플 객체 목록을 사용합니다.

xx://bucketname/object_1
xx://bucketname/object_2
xx://bucketname/path_1/object_3
xx://bucketname/path_1/subpath_1/object_4
xx://bucketname/path_1/subpath_2/object_5
xx://bucketname/path_2/object_6
xx://bucketname/path_2/subpath_3/object_7
xx://bucketname/path_2/subpath_4/object_8

포함 프리픽스 사용

path_1/ 아래에 있는 객체만 전송하려면 다음 프리픽스를 사용합니다.

path_1/

여기에는 path_1/ 아래의 객체가 포함됩니다. 전송에 포함되는 객체는 다음과 같습니다.

xx://bucketname/object_1
xx://bucketname/object_2
xx://bucketname/path_1/object_3
xx://bucketname/path_1/subpath_1/object_4
xx://bucketname/path_1/subpath_2/object_5
xx://bucketname/path_2/object_6
xx://bucketname/path_2/subpath_3/object_7
xx://bucketname/path_2/subpath_4/object_8

포함할 경로를 여러 개 지정할 수 있습니다. 예를 들어 다음을 전달할 수 있습니다.

path_1/subpath_2/
path_1/subpath_3/

이 경우 전송에 다음 객체가 포함됩니다.

xx://bucketname/object_1
xx://bucketname/object_2
xx://bucketname/path_1/object_3
xx://bucketname/path_1/subpath_1/object_4
xx://bucketname/path_1/subpath_2/object_5
xx://bucketname/path_2/object_6
xx://bucketname/path_2/subpath_3/object_7
xx://bucketname/path_2/subpath_4/object_8

부분 일치가 지원됩니다. 예를 들면 다음과 같습니다.

path

다음 객체가 전송됩니다.

xx://bucketname/object_1
xx://bucketname/object_2
xx://bucketname/path_1/object_3
xx://bucketname/path_1/subpath_1/object_4
xx://bucketname/path_1/subpath_2/object_5
xx://bucketname/path_2/object_6
xx://bucketname/path_2/subpath_3/object_7
xx://bucketname/path_2/subpath_4/object_8

포함 프리픽스를 사용하면 특별히 포함하지 않은 경로는 Cloud Storage 대상 버킷으로 전송되지 않습니다.

제외 프리픽스

전송을 만들 때 제외 프리픽스를 사용하면 Storage Transfer Service가 나열된 전송 경로를 무시하도록 지시할 수 있습니다.

path_1/ 아래에 있는 객체를 제외하려면 다음 프리픽스를 전달하세요.

path_1/

path_1/ 아래의 객체는 제외됩니다. 이 경우 다음 객체가 전송에 포함됩니다.

xx://bucketname/object_1
xx://bucketname/object_2
xx://bucketname/path_1/object_3
xx://bucketname/path_1/subpath_1/object_4
xx://bucketname/path_1/subpath_2/object_5
xx://bucketname/path_2/object_6
xx://bucketname/path_2/subpath_3/object_7
xx://bucketname/path_2/subpath_4/object_8

제외할 경로를 여러 개 지정할 수 있습니다. 예를 들어 다음을 전달할 수 있습니다.

path_1/subpath_2/
path_2/subpath_3/

이 경우 전송에 다음 객체가 포함됩니다.

xx://bucketname/object_1
xx://bucketname/object_2
xx://bucketname/path_1/object_3
xx://bucketname/path_1/subpath_1/object_4
xx://bucketname/path_1/subpath_2/object_5
xx://bucketname/path_2/object_6
xx://bucketname/path_2/subpath_3/object_7
xx://bucketname/path_2/subpath_4/object_8

동시에 경로 포함 및 제외

제외 프리픽스와 포함 프리픽스를 함께 적용할 수 있습니다. 이 경우 제외 프리픽스는 전송에 포함된 포함 프리픽스를 제한합니다.

두 가지 유형의 프리픽스를 모두 지정하면 각 제외 프리픽스가 포함 프리픽스에 지정된 경로로 시작해야 합니다.

예를 들어 path_1/ 아래에 객체를 포함하고 subpath_1/ 아래의 객체를 제외하려면 다음을 전달합니다.

include: path_1/
exclude: path_1/subpath_1/

이 경우 전송에 다음 객체가 포함됩니다.

xx://bucketname/object_1
xx://bucketname/object_2
xx://bucketname/path_1/object_3
xx://bucketname/path_1/subpath_1/object_4
xx://bucketname/path_1/subpath_2/object_5
xx://bucketname/path_2/object_6
xx://bucketname/path_2/subpath_3/object_7
xx://bucketname/path_2/subpath_4/object_8

path_1/subpath_1/ 또는 path_2/subpath_3/의 항목을 제외하고 path_1/과 path_2/ 아래의 모든 객체를 포함하려면 다음을 전달합니다.

include: path_1/
         path_2/
exclude: path_1/subpath_1/
         path_2/subpath_3/

이 경우 전송에 다음 객체가 포함됩니다.

xx://bucketname/object_1
xx://bucketname/object_2
xx://bucketname/path_1/object_3
xx://bucketname/path_1/subpath_1/object_4
xx://bucketname/path_1/subpath_2/object_5
xx://bucketname/path_2/object_6
xx://bucketname/path_2/subpath_3/object_7
xx://bucketname/path_2/subpath_4/object_8

피해야 할 일반적인 실수

다음은 잘못된 구성의 예와 이를 수정하는 방법입니다.

다른 포함 프리픽스에 사용되는 경로 포함

포함 프리픽스는 다른 포함 프리픽스의 하위 디렉터리가 될 수 없습니다.

잘못됨: 접두사 path_1/subpath_1은 이미 path_1/에 포함되어 있습니다.

include: path_1/
         path_1/subpath_1

올바름: 이 문제를 해결하려면 중복되고 더 구체적인 접두사를 삭제합니다.

include: path_1/

제외 프리픽스가 포함 프리픽스와 일치하지 않음

함께 사용하는 경우 제외 프리픽스는 포함 프리픽스 중 하나로 시작해야 합니다.

잘못됨: subpath_1 접두사가 path_1/ 또는 path_2/로 시작하지 않습니다.

include: path_1/
         path_2/
exclude: subpath_1

올바름: 제외 프리픽스에 포함 프리픽스의 전체 경로가 포함되어 있는지 확인합니다.

include: path_1/
         path_2/
exclude: path_1/subpath_1/