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 que ficheiros são transferidos.

Vista geral

O Serviço de transferência de armazenamento permite-lhe filtrar dados de origens do Amazon S3, do Microsoft Azure Blob Storage e do Cloud Storage através de prefixos. Um prefixo é uma string de carateres no início de um caminho que especifica um conjunto de objetos.

Pode usar filtros de prefixo de três formas:

Incluir prefixos: apenas 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 em conjunto: pode usar prefixos de inclusão e exclusão em simultâneo para ter um controlo mais detalhado. Quando usados em conjunto, todos os prefixos de exclusão têm de começar com um dos prefixos de inclusão especificados.

Se não especificar prefixos, todos os objetos no contentor de origem são transferidos.

Regras

Aplicam-se as seguintes regras aos prefixos:

Sem barras à esquerda: não inclua uma barra à esquerda num prefixo. Para o caminho s3://my-bucket/logs/2025/requests.gz, o prefixo correto é logs/2025/requests.gz.
Correspondências parciais: os prefixos funcionam através da correspondência parcial. Por exemplo, o prefixo path corresponde a path_1/ e path_2/.
Sem carateres universais: os carateres universais não são suportados.
Relativo à pasta de origem: se a origem da transferência for uma pasta específica, os prefixos são avaliados relativamente a essa pasta. Para uma origem de gs://my-bucket/data/, um prefixo de inclusão de reports corresponde a todos os ficheiros em gs://my-bucket/data/reports.
Prefixos de inclusão distintos: cada prefixo de inclusão tem de definir uma parte única do espaço de nomes do objeto. Não pode usar um prefixo de inclusão que já esteja coberto por outro prefixo de inclusão. Por exemplo, não pode especificar data/ e data/reports/ como prefixos de inclusão.
Excluir dependência de prefixo: quando usar prefixos de inclusão e exclusão em conjunto, todos os prefixos de exclusão têm de começar por um dos prefixos de inclusão especificados. Por exemplo, se path for um prefixo de inclusão, os prefixos de exclusão válidos podem ser path/b ou pathway. Esta regra não se aplica se estiver a usar apenas prefixos de exclusão.
Máximo de 1000 prefixos: uma única tarefa de transferência suporta até 1000 prefixos. Pode dividir uma transferência em várias tarefas se forem necessários prefixos adicionais.

Para ver informações mais gerais sobre prefixos, consulte o artigo Liste chaves hierarquicamente com um prefixo e um delimitador na documentação do Amazon S3 ou o método de lista de objetos para o Cloud Storage.

Como especificar prefixos

Cloud Console

Para especificar prefixos de inclusão e exclusão através da Cloud Console, introduza os valores quando criar uma nova transferência ou quando atualizar uma transferência existente.

CLI gcloud

Para especificar prefixos de inclusão e exclusão através da CLI gcloud, transmita os indicadores --include-prefixes e --exclude-prefixes para o comando gcloud transfer jobs create ou o comando 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 espaços após as vírgulas. Por exemplo, --include-prefixes="foo,bar".

REST

Para especificar prefixos de inclusão e exclusão através da 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 referência ObjectConditions.

Exemplos de objetos e caminhos

Os exemplos seguintes 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

Use prefixos de inclusão

Para transferir apenas objetos em path_1/, use o seguinte prefixo:

path_1/

Isto inclui objetos em path_1/. Os seguintes objetos estã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

Pode especificar vários caminhos a incluir. Por exemplo, pode transmitir o seguinte:

path_1/subpath_2/
path_1/subpath_3/

Neste caso, a transferência inclui os seguintes 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

As correspondências parciais são suportadas. Por 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 usa prefixos de inclusão, os caminhos que não inclui especificamente não são transferidos para o contentor de destino do Cloud Storage.

Exclua prefixos

A utilização de prefixos de exclusão ao criar uma transferência indica ao serviço de transferência de armazenamento que deve ignorar os caminhos indicados para a transferência.

Para excluir objetos em path_1/, transmita o seguinte prefixo:

path_1/

Isto exclui objetos em path_1/. Neste 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

Pode especificar vários caminhos a excluir. Por exemplo, pode transmitir o seguinte:

path_1/subpath_2/
path_2/subpath_3/

Neste caso, a transferência inclui os seguintes 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

Incluir e excluir caminhos em simultâneo

Pode aplicar um prefixo de exclusão e um prefixo de inclusão em conjunto. Neste caso, o prefixo de exclusão limita o que o prefixo de inclusão inclui na transferência.

Quando especifica ambos os tipos de prefixo, cada prefixo de exclusão tem de começar com um caminho especificado num prefixo de inclusão.

Por exemplo, para incluir objetos em path_1/ e excluir objetos em subpath_1/, transmita o seguinte:

include: path_1/
exclude: path_1/subpath_1/

Neste caso, a transferência inclui os seguintes 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 em path_1/ e path_2/, exceto os itens em path_1/subpath_1/ ou path_2/subpath_3/, transmita o seguinte:

include: path_1/
         path_2/
exclude: path_1/subpath_1/
         path_2/subpath_3/

Neste caso, a transferência inclui os seguintes 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 evitar

Seguem-se exemplos de configurações incorretas e como as corrigir.

Incluir um caminho que é usado noutro prefixo de inclusão

Um prefixo de inclusão não pode ser uma subdiretoria de outro prefixo de inclusão.

Incorreto: o caminho do prefixo path_1/subpath_1 já está coberto por path_1/.

include: path_1/
         path_1/subpath_1

Correto: para corrigir este problema, 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 em conjunto, um prefixo de exclusão tem de começar com um dos prefixos de inclusão.

Incorreto: o prefixo subpath_1 não começa com path_1/ nem com path_2/.

include: path_1/
         path_2/
exclude: subpath_1

Correto: certifique-se de que 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/