이 가이드에서는 포함 및 제외 프리픽스를 사용하여 전송되는 파일을 제어하는 방법을 설명합니다.
개요
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/와 모두 일치합니다.와일드 카드 없음: 와일드 카드는 지원되지 않습니다.
소스 폴더를 기준으로: 전송 소스에 경로 또는 폴더가 포함된 경우 접두사는 해당 경로 또는 폴더를 기준으로 합니다. 자세한 내용은 소스 경로 또는 폴더와의 상호작용을 참고하세요.
고유한 포함 프리픽스: 각 포함 프리픽스는 객체 네임스페이스의 고유한 부분을 정의해야 합니다. 이미 다른 포함 프리픽스로 처리된 포함 프리픽스는 사용할 수 없습니다. 예를 들어
data/및data/reports/를 모두 포함 프리픽스로 지정할 수 없습니다.제외 프리픽스 종속 항목: 포함 프리픽스와 제외 프리픽스를 함께 사용하는 경우 모든 제외 프리픽스는 지정된 포함 프리픽스 중 하나로 시작해야 합니다. 예를 들어
path가 포함 프리픽스인 경우 유효한 제외 프리픽스는path/b또는pathway일 수 있습니다. 제외 접두사만 사용하는 경우에는 이 규칙이 적용되지 않습니다.최대 1,000개의 접두사: 단일 전송 작업은 최대 1,000개의 접두사를 지원합니다. 추가 접두사가 필요한 경우 전송을 여러 작업으로 분할할 수 있습니다.
더 일반적인 프리픽스 정보는 Amazon S3 문서의 프리픽스와 구분자를 사용하여 계층적 구조로 키 나열 또는 Cloud Storage의 Objects list 메서드를 참고하세요.
다른 필터 유형과의 상호작용
필터를 여러 개 사용하는 경우 Storage Transfer Service는 다음 순서로 적용합니다.
프리픽스 포함: 고려할 객체의 범위를 좁힙니다.
객체 조건 (마지막 수정 시간): 포함 접두사와 일치하는 객체를 필터링합니다. 결과에 포함되려면 객체가 마지막 수정 필터와 일치해야 합니다.
접두사 제외: 결과에서 객체를 삭제합니다.
소스 경로 또는 폴더와의 상호작용
포함 및 제외 필터는 소스에 지정한 경로 또는 폴더를 기준으로 합니다.
예를 들어 소스가 gs://bucketA/alpha이고 gs://bucketA/alpha/beta의 필터를 지정하려면 다음을 실행합니다.
정답
- 소스 경로:
gs://bucketA/alpha - 접두사 제외:
beta/ - 결과:
gs://bucketA/alpha/beta가 올바르게 제외됩니다.
잘못됨
- 소스 경로:
gs://bucketA/alpha - 접두사 제외:
alpha/beta/ - 결과:
gs://bucketA/alpha/alpha/beta의 필터를 잘못 정의합니다.
접두사 지정
Google Cloud 콘솔
Google 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": "Transfer with prefixes",
"status": "ENABLED",
"projectId": "PROJECT_ID",
"schedule": {
"scheduleStartDate": {
"day": 1,
"month": 1,
"year": 2015
},
"startTimeOfDay": {
"hours": 1,
"minutes": 1
}
},
"transferSpec": {
"gcsDataSource": {
"bucketName": "SOURCE_BUCKET"
},
"gcsDataSink": {
"bucketName": "DESTINATION_BUCKET"
},
"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_1xx://bucketname/object_2xx://bucketname/path_1/object_3 xx://bucketname/path_1/subpath_1/object_4 xx://bucketname/path_1/subpath_2/object_5xx://bucketname/path_2/object_6xx://bucketname/path_2/subpath_3/object_7xx://bucketname/path_2/subpath_4/object_8
포함할 경로를 여러 개 지정할 수 있습니다. 예를 들어 다음을 전달할 수 있습니다.
path_1/subpath_2/ path_2/subpath_3/
이 경우 전송에 다음 객체가 포함됩니다.
xx://bucketname/object_1xx://bucketname/object_2xx://bucketname/path_1/object_3xx://bucketname/path_1/subpath_1/object_4xx://bucketname/path_1/subpath_2/object_5xx://bucketname/path_2/object_6xx://bucketname/path_2/subpath_3/object_7xx://bucketname/path_2/subpath_4/object_8
부분 일치가 지원됩니다. 예를 들면 다음과 같습니다.
path
다음 객체가 전송됩니다.
xx://bucketname/object_1xx://bucketname/object_2xx://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_2xx://bucketname/path_1/object_3xx://bucketname/path_1/subpath_1/object_4xx://bucketname/path_1/subpath_2/object_5xx://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_4xx://bucketname/path_1/subpath_2/object_5xx://bucketname/path_2/object_6xx://bucketname/path_2/subpath_3/object_7xx://bucketname/path_2/subpath_4/object_8
동시에 경로 포함 및 제외
제외 프리픽스와 포함 프리픽스를 함께 적용할 수 있습니다. 이 경우 제외 프리픽스는 전송에 포함된 포함 프리픽스를 제한합니다.
두 가지 유형의 프리픽스를 모두 지정하면 각 제외 프리픽스가 포함 프리픽스에 지정된 경로로 시작해야 합니다.
예를 들어 path_1/ 아래에 객체를 포함하고 subpath_1/ 아래의 객체를 제외하려면 다음을 전달합니다.
include: path_1/
exclude: path_1/subpath_1/
이 경우 전송에 다음 객체가 포함됩니다.
xx://bucketname/object_1xx://bucketname/object_2xx://bucketname/path_1/object_3xx://bucketname/path_1/subpath_1/object_4xx://bucketname/path_1/subpath_2/object_5xx://bucketname/path_2/object_6xx://bucketname/path_2/subpath_3/object_7xx://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_1xx://bucketname/object_2xx://bucketname/path_1/object_3xx://bucketname/path_1/subpath_1/object_4xx://bucketname/path_1/subpath_2/object_5 xx://bucketname/path_2/object_6xx://bucketname/path_2/subpath_3/object_7xx://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/