Filtrar objetos de origem usando caracteres curingas

Os jobs do Serviço de transferência do Cloud Storage aceitam strings de pesquisa com caracteres curinga, como * e ?, para corresponder a nomes de arquivos ou caminhos. Essas strings de pesquisa são chamadas de padrões glob.

É possível usar padrões glob para especificar quais objetos de origem incluir em uma transferência. Isso permite um controle mais refinado do que a filtragem apenas por prefixo.

A filtragem com padrões glob é compatível com transferências da AWS S3 e do Azure.

Sintaxe de glob

Um padrão glob usa a seguinte sintaxe para corresponder a caminhos de objetos:

Sintaxe Descrição
? Corresponde a qualquer caractere único, exceto /.
* Corresponde a zero ou mais caracteres, exceto /.
** Corresponde a zero ou mais caracteres, incluindo /.
[abc] Corresponde a exatamente um dos caracteres (por exemplo, a, b ou c).
[a-z] Corresponde a exatamente um caractere no intervalo inclusivo (por exemplo, a a z).
[!abc] ou [^abc] Corresponde a exatamente um caractere que não seja a, b ou c.
{abc,xyz} Corresponde a uma das strings (por exemplo, abc ou xyz). Não pode conter barras (/) ou asteriscos duplos (**).
\? Corresponde ao caractere literal após a barra invertida (por exemplo, \? corresponde a um ? literal).

Exemplos de padrões

Corresponda a todos os arquivos .log dos diretórios december:

logs_by_year/**/december/*.log

Transfira todos os arquivos no diretório data_analytics/ que não começam com um . (ponto) ou _ (sublinhado):

data_analytics/[!._]*

Para tornar o exemplo anterior recursivo:

data_analytics/**/[!._]*

Transfira todos os arquivos PDF de exatamente dois diretórios específicos:

quarterly_reports/2025/{q1-final,q4-final}/*.pdf

Especificar um padrão glob

É possível especificar um padrão glob ao criar ou atualizar um job de transferência.

CLI da gcloud

Para filtrar por padrão glob usando a CLI gcloud, transmita a flag --match-glob para o comando gcloud transfer jobs create ou gcloud transfer jobs update:

gcloud transfer jobs create SOURCE DESTINATION \
  --match-glob="GLOB_PATTERN"

Exemplo:

O comando a seguir cria um job que transfere apenas arquivos .log dos diretórios december:

gcloud transfer jobs create s3://my-source-bucket gs://my-sink-bucket \
  --match-glob="logs_by_year/**/december/*.log"

REST

Para filtrar por padrão glob usando a API REST, especifique o campo matchGlob no objectConditions do seu transferSpec.

{
  "description": "Transfer December logs from all years",
  "status": "ENABLED",
  "projectId": "PROJECT_ID",
  "transferSpec": {
    "awsS3DataSource": {
      "bucketName": "AWS_SOURCE_NAME",
      "awsAccessKey": {
        "accessKeyId": "AWS_ACCESS_KEY_ID",
        "secretAccessKey": "AWS_SECRET_ACCESS_KEY"
      }
    },
    "gcsDataSink": {
      "bucketName": "DESTINATION_BUCKET"
    },
    "objectConditions": {
      "matchGlob": "logs_by_year/**/december/*.log"
    }
  }
}

Para mais informações, consulte a referência de ObjectConditions.

Console do Google Cloud

Não é possível filtrar por padrão glob no console do Google Cloud.

Interação com outros filtros

Quando você usa um filtro de padrão glob com filtros de prefixo ou de hora da última modificação, o Serviço de transferência do Cloud Storage aplica os filtros na seguinte ordem:

  1. Incluir prefixos: restringe os objetos a serem considerados.

  2. Condições de objeto (padrão glob e horário da última modificação): filtra os objetos que corresponderam ao prefixo de inclusão. Um objeto precisa corresponder ao filtro de glob e ao filtro de hora da última modificação para ser incluído no resultado.

  3. Excluir prefixos: remove objetos do resultado.

Saiba mais sobre filtrar por prefixo e filtrar por hora da última modificação.

Prefixos de inclusão

O padrão glob é aplicado apenas a objetos que correspondem a pelo menos um prefixo de inclusão.

O Serviço de transferência do Cloud Storage retorna um erro se o padrão glob contradizer todos os padrões de prefixo de inclusão.

Exemplo: combinação válida

  • include_prefix: ["foo/"]
  • match_glob: "foo/bar/**"

Resultado:válido. Primeiro, o serviço lista os objetos em foo/ e depois aplica o padrão glob a essa lista.

Exemplo: combinação válida

  • include_prefix: ["logs/2024/", "logs/2025/"]
  • match_glob: "**/*.json"

Resultado:válido. O serviço lista todos os objetos nos diretórios 2024 e 2025 e transfere apenas os arquivos que terminam com .json.

Exemplo: contradição

  • include_prefix: ["foo/"]
  • match_glob: "bar/**"

Resultado:erro. O padrão match_glob não pode corresponder a nenhum objeto selecionado pelo include_prefix.

Prefixos de exclusão

O filtro de prefixo de exclusão é aplicado depois do filtro de prefixo de inclusão e do filtro de padrão glob.

Nenhuma verificação de contradição é realizada. Qualquer objeto que corresponda a um prefixo de exclusão é removido da lista de transferência, mesmo que corresponda ao padrão glob.

Exemplo

  • include_prefix: ["logs/"]
  • match_glob: "**/*.log"
  • exclude_prefix: ["logs/temp/"]

Resultado:o serviço transfere todos os objetos em logs/ que terminam com .log, exceto aqueles no diretório logs/temp/.