本指南介绍了如何使用包含和排除前缀来控制要转移的文件。
概览
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。如果您仅使用排除前缀，则此规则不适用。最多 1000 个前缀：单个转移作业最多支持 1000 个前缀。如果需要其他前缀，您可以将转移拆分为多个作业。
如需了解有关前缀的更多常规信息，请参阅 Amazon S3 文档中的使用前缀和分隔符分层列出密钥或 Cloud Storage 的对象 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 控制台
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 目标存储桶。
排除前缀
创建转移作业时，使用排除前缀指示 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/ 和 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/