Filtrar por prefixo

Nesta página, mostramos como incluir e excluir caminhos de transferências usando prefixos de inclusão e exclusão.

Saiba como criar um manifesto de objetos específicos a serem transferidos em Transferir arquivos ou objetos específicos usando um manifesto.

Visão geral

O Serviço de transferência do Cloud Storage oferece suporte ao uso de prefixos para selecionar quais arquivos incluir ou excluir da fonte de dados. É possível usar prefixos de inclusão, exclusão ou ambos.

As fontes de dados do Amazon S3, do armazenamento de blobs do Microsoft Azure e do Cloud Storage oferecem suporte para filtragem por prefixo.

  • Não inclua a barra inicial em um prefixo. Por exemplo, para incluir o objeto requests.gz em uma transferência do caminho de bucket s3://my-aws-bucket/logs/y=2015/requests.gz, especifique o prefixo de inclusão como logs/y=2015/requests.gz.

  • As correspondências parciais são compatíveis com prefixos de inclusão e exclusão. Por exemplo, path corresponde a path_1/ e path_2/.

  • Caracteres curinga não são aceitos.

  • Se você tiver especificado uma pasta como local de origem, os filtros de prefixo serão relativos a essa pasta. Por exemplo, se a origem for gs://my-test-bucket/path/, um filtro de inclusão de file inclui todos os arquivos começando com gs://my-test-bucket/path/file.

  • Cada prefixo de inclusão precisa incluir uma parte distinta do namespace do objeto. Nenhum prefixo de inclusão pode ser um prefixo de outro. Por exemplo, não é possível especificar path_1 e path_1/subpath_2 como prefixos de inclusão.

  • Se você usar prefixos de inclusão e de exclusão juntos, os prefixos de exclusão precisam começar com o valor de um dos prefixos de inclusão. Por exemplo, se você especificar a como prefixo de inclusão, os prefixos de exclusão válidos serão a/b, aaa e abc.

  • Se você usar apenas prefixos de exclusão, não haverá restrições nos prefixos que podem ser usados.

  • Se você não especificar prefixos, todos os objetos no bloco serão transferidos.

Para mais informações gerais sobre prefixos, consulte Como listar chaves hierarquicamente usando 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

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

Nos exemplos deste documento, usaremos os caminhos e objetos de amostra abaixo:

xx://bucketname/object_1
xx://bucketname/object_2
xx://bucketname/path_1/object_3
xx://bucketname/path_2/object_4
xx://bucketname/path_1/subpath_1/object_5
xx://bucketname/path_1/subpath_2/object_6
xx://bucketname/path_2/subpath_3/object_7
xx://bucketname/path_2/subpath_4/object_8

Prefixos de inclusão

Use prefixos de inclusão ao criar uma transferência para instruir o Serviço de transferência do Cloud Storage a considerar objetos nos caminhos listados para transferência e ignorar objetos que não estejam nesses caminhos.

Por exemplo, para incluir objetos em path_1/, use o seguinte prefixo:

path_1/

Isso inclui objetos diretamente em path_1/, path_1/subpath_1 e path_1/subpath_2/. 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_2/object_4
xx://bucketname/path_1/subpath_1/object_5
xx://bucketname/path_1/subpath_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_2/object_4
xx://bucketname/path_1/subpath_1/object_5
xx://bucketname/path_1/subpath_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. Por exemplo, especificar path como o valor de um prefixo de inclusão corresponde aos seguintes objetos:

xx://bucketname/object_1
xx://bucketname/object_2
xx://bucketname/path_1/object_3
xx://bucketname/path_2/object_4
xx://bucketname/path_1/subpath_1/object_5
xx://bucketname/path_1/subpath_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/, path_1/subpath_1/ e path_1/subpath_2/. 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_2/object_4
xx://bucketname/path_1/subpath_1/object_5
xx://bucketname/path_1/subpath_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_2/object_4
xx://bucketname/path_1/subpath_1/object_5
xx://bucketname/path_1/subpath_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_2/object_4
xx://bucketname/path_1/subpath_1/object_5
xx://bucketname/path_1/subpath_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_2/object_4
xx://bucketname/path_1/subpath_1/object_5
xx://bucketname/path_1/subpath_2/object_6
xx://bucketname/path_2/subpath_3/object_7
xx://bucketname/path_2/subpath_4/object_8

Exemplos de inclusão ou exclusão incorreta de caminhos

Nas seções a seguir, veja exemplos do que deve ser evitado ao usar caminhos de inclusão ou exclusão e saiba como corrigi-los, para que funcionem corretamente.

Como incluir um caminho usado em outro prefixo de inclusão

Cada prefixo de inclusão precisa especificar uma parte distinta do namespace do objeto. O exemplo a seguir está incorreto porque o segundo valor já está incluído no namespace do primeiro valor:

include: path_1/
         path_1/subpath_1

Neste exemplo, os valores de prefixo de inclusão são inválidos porque o segundo prefixo de inclusão, path_1/subpath_1, já está incluído em path_1/. Para corrigir isso, remova um dos valores.

Usar um prefixo de exclusão que não comece com um prefixo de inclusão

Cada prefixo de exclusão precisa começar com qualquer um dos valores de prefixo de inclusão especificados. O exemplo a seguir está incorreto porque os valores de prefixo de exclusão não começam com os valores de prefixo de inclusão especificados:

include: path_1/
         path_2/
exclude: subpath_1
         subpath_4

Neste exemplo, os valores de prefixo de exclusão são inválidos porque não começam com nenhum dos valores de prefixo de inclusão. Para corrigir isso, verifique se o prefixo de exclusão inclui um caminho completo listado como um prefixo de inclusão:

include: path_1/
         path_2/
exclude: path_1/subpath_1/
         path_2/subpath_4/

A seguir