此页面由 Cloud Translation API 翻译。

按前缀过滤

本指南介绍了如何使用包含和排除前缀来控制要转移的文件。

概览

借助 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。如果您仅使用排除前缀，则此规则不适用。
最多 1000 个前缀：单个转移作业最多支持 1000 个前缀。如果需要其他前缀，您可以将转移拆分为多个作业。

如需了解有关前缀的更多常规信息，请参阅 Amazon S3 文档中的使用前缀和分隔符分层列出密钥或 Cloud Storage 的对象 list 方法。

如何指定前缀

Cloud 控制台

如需使用 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": "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/ 和 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/