按前缀过滤源对象

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

概览

Storage Transfer Service 支持使用前缀过滤来自 Amazon S3、Microsoft Azure Blob Storage 和 Cloud Storage 来源的数据。前缀是路径开头的一串字符,用于指定一组对象。

您可以通过以下三种方式使用前缀过滤条件:

  • 包含前缀:仅转移与指定前缀匹配的对象。

  • 排除前缀:与指定前缀匹配的对象会从转移作业中省略。

  • 同时使用:您可以同时使用包含前缀和排除前缀,以实现更精细的控制。如果同时使用,则每个排除前缀都必须以其中一个指定的包含前缀开头。

如果未指定任何前缀,则将传输来源存储桶中的所有对象。

前缀过滤条件可以与 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 文档中的使用前缀和定界符分层列出密钥或 Cloud Storage 的对象 list 方法。

与其他过滤条件类型的交互

如果您使用多个过滤条件,Storage Transfer Service 会按以下顺序应用这些过滤条件:

  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 目标存储桶。

排除前缀

创建转移作业时,使用排除前缀指示 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/