本指南說明如何使用包含和排除前置字元,控管要移轉的檔案。
總覽
Storage 移轉服務支援使用前置字串,篩選 Amazon S3、Microsoft Azure Blob Storage 和 Cloud Storage 來源的資料。前置字串是路徑開頭的一串字元,用於指定一組物件。
前置字元篩選器有三種使用方式:
納入前置字串:只移轉與指定前置字串相符的物件。
排除前置字串:轉移作業會略過與指定前置字串相符的物件。
兩者並用:您可以同時使用納入和排除前置字元,進行更精細的控制。如果同時使用,每個排除前置字串都必須以指定的納入前置字串開頭。
如未指定任何前置字串,系統會移轉來源 bucket 中的所有物件。
前置字元篩選器可與 glob 模式、上次修改時間篩選器和 S3 儲存空間級別篩選器搭配使用。
規則
前置字串適用下列規則:
開頭不含斜線:前置字元開頭不得包含斜線。路徑
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 個納入前置字串和 1,000 個排除前置字串。如需更多前置字元,可以將轉移作業拆分為多項工作。
如需前置字串的一般資訊,請參閱 Amazon S3 說明文件中的「Listing Keys Hierarchically Using a Prefix and Delimiter」(使用前置字串和分隔符號以階層方式列出金鑰),或 Cloud Storage 的物件清單方法。
與其他篩選器類型的互動
使用多個篩選器時,Storage 移轉服務會依下列順序套用:
- 納入前置字串:縮小要考量的物件範圍。
- 物件條件 (glob 模式、上次修改時間和 S3 儲存空間級別):篩選符合納入前置字元的物件。物件必須符合所有指定的物件條件,才能納入移轉作業。
- 排除前置字串:從結果中移除物件。
進一步瞭解如何使用 glob 模式、上次修改時間和 S3 儲存空間級別進行篩選。
與來源路徑或資料夾互動
「包含」和「排除」篩選器會套用至您為來源指定的任何路徑或資料夾。
舉例來說,如果來源是 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 控制台
gcloud CLI
如要使用 gcloud CLI 指定包含和排除前置字串,請將 --include-prefixes 和 --exclude-prefixes 旗標傳遞至 gcloud transfer jobs create 指令或 gcloud transfer jobs update 指令:
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 目的地 bucket。
排除前置字串
建立移轉作業時,如果使用排除前置字串,Storage 移轉服務就會忽略列出的路徑。
如要排除 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/ 和 path_2/ 下的所有物件,但不包含 path_1/subpath_1/ 或 path_2/subpath_3/ 中的項目,請傳遞下列內容:
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/