Esta página foi traduzida pela API Cloud Translation.

Filtrar por prefixo

Este guia explica 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 permite filtrar 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.

Você pode 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 ter um controle mais granular. Quando usados juntos, todos os prefixos de exclusão precisam 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.

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 path corresponde a path_1/ e path_2/.
Sem caracteres curinga: não há suporte para caracteres curinga.
Relativo à pasta de origem: se a origem da transferência for uma pasta específica, os prefixos serão avaliados em relação a ela. Para uma origem de gs://my-bucket/data/, um prefixo de inclusão de reports corresponde a todos os arquivos em gs://my-bucket/data/reports.
Prefixos de inclusão 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. Por exemplo, não é possível especificar data/ e data/reports/ como prefixos de inclusã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 path for um prefixo de inclusão, os prefixos de exclusão válidos poderão ser path/b ou pathway. Essa regra não se aplica se você estiver usando apenas prefixos de exclusão.
Máximo de 1.000 prefixos: um único job de transferência aceita até 1.000 prefixos. É possível dividir uma transferência em vários jobs se forem necessários prefixos adicionais.

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.

Como especificar prefixos

Console do Cloud

Para especificar prefixos de inclusão e exclusão usando o console do 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": "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"
            ]
        }
    }
}

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 de amostra:

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_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

É possível especificar vários caminhos a serem incluídos. Por exemplo, transmita o seguinte:

path_1/subpath_2/
path_1/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_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

Correspondências parciais são aceitas. Exemplo:

path

Os seguintes objetos são transferidos:

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

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_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

É 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_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

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_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

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_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

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, 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/ ou 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/