Neste guia, explicamos como usar prefixos de inclusão e exclusão para controlar quais arquivos são transferidos.
Visão geral
O Serviço de transferência do Cloud Storage é compatível com a filtragem de dados de fontes do Amazon S3, do Armazenamento de Blobs do Microsoft Azure e do Cloud Storage usando prefixos. Um prefixo é uma string de caracteres no início de um caminho que especifica um conjunto de objetos.
É possível usar filtros de prefixo de três maneiras:
Incluir prefixos: somente os objetos que correspondem aos prefixos especificados são transferidos.
Excluir prefixos: os objetos que correspondem aos prefixos especificados são omitidos da transferência.
Ambos juntos: é possível usar prefixos de inclusão e exclusão simultaneamente para um controle mais granular. Quando usados juntos, cada prefixo de exclusão precisa começar com um dos prefixos de inclusão especificados.
Se você não especificar prefixos, todos os objetos no bucket de origem serão transferidos.
Os filtros de prefixo podem ser combinados com padrões glob, filtros de horário da última modificação e filtros de classe de armazenamento do S3.
Regras
As seguintes regras se aplicam aos prefixos:
Sem barras iniciais: não inclua uma barra inicial em um prefixo. Para o caminho
s3://my-bucket/logs/2025/requests.gz, o prefixo correto élogs/2025/requests.gz.Correspondências parciais: os prefixos funcionam por correspondência parcial. Por exemplo, o prefixo
pathcorresponde apath_1/epath_2/.Sem caracteres curinga: caracteres curinga não são aceitos.
Relativo à pasta de origem: se a origem da transferência incluir um caminho ou uma pasta, os prefixos serão relativos a esse caminho ou pasta. Consulte Interação com o caminho ou a pasta de origem para mais detalhes.
Prefixos distintos: cada prefixo de inclusão precisa definir uma parte exclusiva do namespace do objeto. Não é possível usar um prefixo de inclusão que já esteja coberto por outro prefixo de inclusão. Por exemplo, não é possível especificar
data/edata/reports/como prefixos de inclusão. A mesma regra se aplica entre prefixos de exclusão.Dependência de prefixo de exclusão: ao usar prefixos de inclusão e exclusão juntos, cada prefixo de exclusão precisa começar com um dos prefixos de inclusão especificados. Por exemplo, se
pathfor um prefixo de inclusão, os prefixos de exclusão válidos poderão serpath/boupathway. Essa regra não se aplica se você estiver usando apenas prefixos de exclusão.Máximo de 1.000 prefixos de cada tipo: um único job de transferência aceita até 1.000 prefixos de inclusão e até 1.000 prefixos de exclusão. É possível dividir uma transferência em vários jobs se forem necessários mais prefixos.
Para mais informações gerais sobre prefixos, consulte Como listar chaves hierarquicamente usando um prefixo e delimitador na documentação do Amazon S3 ou o Método de lista de objetos para o Cloud Storage.
Interação com outros tipos de filtros
Quando você usa vários filtros, o Serviço de transferência do Cloud Storage os aplica na seguinte ordem:
- Incluir prefixos: restringe os objetos a serem considerados.
- Condições do objeto (padrão glob, horário da última modificação e classe de armazenamento do S3): filtra os objetos que correspondem ao prefixo de inclusão. Um objeto precisa corresponder a todas as condições especificadas para ser incluído na transferência.
- Excluir prefixos: remove objetos do resultado.
Saiba mais sobre como filtrar com padrões glob, horário da última modificação e classe de armazenamento do S3.
Interação com o caminho ou a pasta de origem
Os filtros de inclusão e exclusão são relativos a qualquer caminho ou pasta que você especificar para a origem.
Por exemplo, se a origem for gs://bucketA/alpha e você quiser especificar
um filtro para gs://bucketA/alpha/beta:
Correto
- Caminho de origem:
gs://bucketA/alpha - Prefixo de exclusão:
beta/ - Resultado: exclui corretamente
gs://bucketA/alpha/beta
Incorreto
- Caminho de origem:
gs://bucketA/alpha - Prefixo de exclusão:
alpha/beta/ - Resultado: isso define incorretamente um filtro para
gs://bucketA/alpha/alpha/beta
Especificar prefixos
Console do Google Cloud
Para especificar prefixos de inclusão e exclusão usando o console doGoogle Cloud , insira os valores ao criar uma nova transferência ou ao atualizar uma transferência atual.
CLI da gcloud
Para especificar prefixos de inclusão e exclusão usando a CLI gcloud, transmita as flags
--include-prefixes e --exclude-prefixes para o
comando gcloud transfer jobs create ou
gcloud transfer jobs update:
gcloud transfer jobs create SOURCE DESTINATION \
--include-prefixes="path_1/,path_2/" --exclude-prefixes="path_1/subpath_2/"
Separe vários prefixos com vírgulas, omitindo os espaços após as vírgulas.
Por exemplo, --include-prefixes="foo,bar".
REST
Para especificar prefixos de inclusão e exclusão com a API REST, use os campos
includePrefixes[] e 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"
]
}
}
}
Para mais informações, consulte a documentação de referência deObjectConditions.
Objetos e caminhos de exemplo
Os exemplos a seguir usam esta lista de objetos:
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
Usar prefixos de inclusão
Para transferir apenas objetos em path_1/, use o seguinte prefixo:
path_1/
Isso inclui objetos em path_1/. Estes objetos são incluídos na transferência:
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
É possível especificar vários caminhos a serem incluídos. Por exemplo, transmita o seguinte:
path_1/subpath_2/ path_2/subpath_3/
Nesse caso, a transferência inclui estes objetos:
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
Correspondências parciais são aceitas. Exemplo:
path
Os seguintes objetos são transferidos:
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
Quando você usa prefixos de inclusão, os caminhos que não inclui de forma específica não são transferidos para o bucket de destino do Cloud Storage.
Prefixos de exclusão
O uso de prefixos de exclusão ao criar uma transferência instrui o Serviço de transferência do Cloud Storage a ignorar os caminhos listados para transferência.
Para excluir objetos de path_1/, transmita o seguinte prefixo:
path_1/
Isso exclui objetos de path_1/. Nesse caso, os seguintes objetos são incluídos na transferência:
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
É possível especificar vários caminhos a serem excluídos. Por exemplo, transmita o seguinte:
path_1/subpath_2/
path_2/subpath_3/
Nesse caso, a transferência inclui estes objetos:
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
Como incluir e excluir caminhos simultaneamente
É possível aplicar um prefixo de exclusão e um de inclusão juntos. Nesse caso, o prefixo de exclusão limita o que o prefixo de inclusão inclui na transferência.
Ao especificar os dois tipos de prefixo, cada prefixo de exclusão precisa começar com um caminho especificado em um prefixo de inclusão.
Por exemplo, para incluir objetos de path_1/ e excluir objetos de
subpath_1/, transmita:
include: path_1/
exclude: path_1/subpath_1/
Nesse caso, a transferência inclui estes objetos:
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
Para incluir todos os objetos de path_1/ e path_2/, exceto os itens de
path_1/subpath_1/ ou path_2/subpath_3/, transmita:
include: path_1/
path_2/
exclude: path_1/subpath_1/
path_2/subpath_3/
Nesse caso, a transferência inclui estes objetos:
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
Erros comuns a serem evitados
Confira exemplos de configurações incorretas e como corrigi-las.
Como incluir um caminho usado em outro prefixo de inclusão
Um prefixo de inclusão não pode ser um subdiretório de outro prefixo de inclusão.
Incorreto: o prefixo path_1/subpath_1 já está coberto por path_1/.
include: path_1/
path_1/subpath_1
Correto: para corrigir isso, remova o prefixo redundante e mais específico.
include: path_1/
O prefixo de exclusão não corresponde a um prefixo de inclusão
Quando usados juntos, um prefixo de exclusão precisa começar com um dos prefixos de inclusão.
Incorreto: o prefixo subpath_1 não começa com path_1/ nem
path_2/.
include: path_1/
path_2/
exclude: subpath_1
Correto: verifique se o prefixo de exclusão contém o caminho completo de um prefixo de inclusão.
include: path_1/
path_2/
exclude: path_1/subpath_1/