本頁面由 Cloud Translation API 翻譯而成。

按照前置字串篩選

本指南說明如何使用「納入」及「排除」前置字串，控管要轉移哪些檔案。

總覽

Storage 移轉服務可讓您使用前置字串，篩選 Amazon S3、Microsoft Azure Blob 儲存體和 Cloud Storage 來源的資料。前置字元是路徑開頭的字元字串，用於指定一組物件。

前置字串篩選器有三種用法：

納入前置字串：只轉移與指定前置字串相符的物件。
排除前置字串：系統會從轉移作業中省略符合指定前置字串的物件。
同時使用兩者：您可以同時使用「納入」和「排除」前置字串，進一步控管。如果同時使用這兩者，每個排除前置字串的開頭都必須是其中一個指定的納入前置字串。

如果不指定任何前置字串，則來源 bucket 中的所有物件都會一併移轉。

規則

前置字元適用下列規則：

不得有開頭斜線：前置字串不得包含開頭斜線。路徑 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 下的所有檔案。
不同的 include 前置字元：每個 include 前置字元都必須定義物件命名空間的專屬部分。您無法使用已由其他納入前置字串涵蓋的納入前置字串。舉例來說，您無法同時指定 data/ 和 data/reports/ 做為納入前置字串。
排除前置字串的依附元件：同時使用「納入」和「排除」前置字串時，每個「排除」前置字串的開頭都必須是其中一個指定的「納入」前置字串。舉例來說，如果 path 是「納入」前置字串，有效的「排除」前置字串可能是 path/b 或 pathway。如果您只使用「排除」前置字串，則不適用這項規則。
最多 1000 個前置字元：單一移轉工作最多支援 1000 個前置字元。如果需要其他前置字元，您可以將轉移作業分成多個工作。

如需前置字串的一般資訊，請參閱 Amazon S3 說明文件中的「使用前置字串與分隔符號以階層方式列出金鑰」，或是 Cloud Storage 的「物件清單列出方法」。

如何指定前置字串

Cloud 控制台

如要使用 Cloud Console 指定納入和排除前置字串，請在建立新移轉作業或更新現有移轉作業時輸入值。

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": "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 目的地 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

應避免的常見錯誤

以下列舉幾個設定錯誤的例子，並說明如何修正。

包含其他 include 前置字串中使用的路徑

包含前置字串不得為另一個包含前置字串的子目錄。

錯誤：前置路徑 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/