依前置字串篩選來源物件

本指南說明如何使用包含和排除前置字元,控管要移轉的檔案。

總覽

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 移轉服務會依下列順序套用:

  1. 納入前置字串:縮小要考量的物件範圍。
  2. 物件條件 (glob 模式、上次修改時間和 S3 儲存空間級別):篩選符合納入前置字元的物件。物件必須符合所有指定的物件條件,才能納入移轉作業。
  3. 排除前置字串:從結果中移除物件。

進一步瞭解如何使用 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 控制台

如要使用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_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

系統會轉移下列物件:

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 目的地 bucket。

排除前置字串

建立移轉作業時,如果使用排除前置字串,Storage 移轉服務就會忽略列出的路徑。

如要排除 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/ 和 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_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/