Nomes de caractere curinga

Descrição

O gsutil é compatível com caracteres curinga de URI para arquivos, buckets e objetos. Por exemplo, o comando:

gsutil cp gs://bucket/data/abc* .

copiará todos os objetos que começam com gs://bucket/data/abc seguido de qualquer número de caracteres dentro desse subdiretório.

Caracteres curinga

A gsutil usa os seguintes caracteres curinga:

*
Corresponde a qualquer número de caracteres no nível do diretório atual. Por exemplo, gs://my-bucket/abc/d* corresponde ao objeto abc/def.txt, mas não ao objeto abc/def/g.txt.
**

Corresponde qualquer número de caracteres entre limites de diretório. Quando usados como parte de um caminho do arquivo local, o caractere curinga ** precisa ser imediatamente precedido por um delimitador de diretório. Por exemplo, my-directory/**.txt é válido, mas my-directory/abc** não é.

?
Corresponder a um único caractere. Por exemplo, gs://bucket/??.txt corresponde apenas a objetos com dois caracteres seguidos por .txt.
[caracteres]
Corresponde a qualquer um dos caracteres especificados. Por exemplo, gs://bucket/[aeiou].txt corresponde a objetos que contêm um único caractere de vogal seguido de .txt.
[intervalo de caracteres]
Corresponde a qualquer um dos intervalos de caracteres. Por exemplo, gs://bucket/[a-m].txt corresponde a objetos que contêm letras a, b, c, ... ou m e terminam com .txt.

É possível combinar caracteres curinga para fornecer correspondências mais poderosas, por exemplo:

gs://*/[a-m]??.j*g

A menos que seu comando inclua uma sinalização para retornar versões de objeto não atuais nos resultados, esses caracteres curinga correspondem apenas às versões de objetos ativos.

A gsutil é compatível com os mesmos caracteres curinga para nomes de arquivo e objeto. Assim, por exemplo:

gsutil cp data/abc* gs://bucket

corresponde a todos os arquivos que começam com abc no diretório data do sistema de arquivos local.

Potencial comportamento inesperado ao usar caracteres curinga

Algumas maneiras de usar caracteres curinga podem resultar em comportamentos inesperados:

  1. Ao usar caracteres curinga em nomes de bucket, as correspondências são limitadas a buckets no projeto especificado na sinalização -p. Alguns comandos, como gsutil rm, não são compatíveis com a sinalização -p. Se a sinalização -p não for ou não puder ser usada em um comando, as correspondências serão limitadas a buckets no projeto padrão.

  2. Os shell (como bash e zsh) podem tentar expandir caracteres curinga antes de passar os argumentos para o gsutil. Se o caractere curinga foi usado para se referir a um objeto na nuvem, isso pode causar erros surpreendentes de "Não encontrado". Por exemplo, se o shell tentar expandir o caractere curinga gs://my-bucket/* na máquina local, que não corresponde a nenhum arquivo local e falha no comando.

    Algumas shells incluem caracteres adicionais nos conjuntos de caracteres curinga. Por exemplo, se você usar zsh com a opção extendedglob ativada, ele trata # como um caractere especial, que entra em conflito com o uso desse caractere na referência de objetos com versão. Consulte Restaurar objeto não atual para ver um exemplo.

    Para evitar esses problemas, coloque a expressão curinga entre aspas simples (no Linux) ou aspas duplas (no Windows).

  3. A tentativa de especificar um nome de arquivo que contenha caracteres curinga não funcionará, porque o gsutil tentará expandi-los em vez de usá-los como caracteres literais. Por exemplo, execute o comando:

    gsutil cp './file[1]' gs://my-bucket
    

    faz com que o gsutil tente corresponder a parte do [1] como um caractere curinga.

    Há uma solicitação em aberto para oferecer suporte ao modo "bruto" e fazer com que o gsutil forneça uma maneira de trabalhar com nomes de arquivos que contêm caracteres curinga. No entanto, até que o suporte seja resolvido, não há uma boa maneira de usar gsutil com esses nomes de arquivo. É possível usar um caractere curinga para nomear esses arquivos, por exemplo, substituindo o comando acima por:

    gsutil cp './file*1*' gs://my-bucket
    

    mas, em geral, é difícil usar essa abordagem.

Comportamento diferente para arquivos "Dot" no sistema de arquivos local

De acordo com o comportamento Unix padrão, o caractere curinga * corresponde somente a arquivos que não começam com um caractere . (para evitar confusão com os diretórios . e .. presentes em todos os diretórios Unix). A gsutil fornece esse mesmo comportamento ao usar caracteres curinga em um URI do sistema de arquivos, mas não fornece esse comportamento nos URIs da nuvem. Por exemplo, o comando a seguir copia todos os objetos de gs://bucket1 para gs://bucket2:

gsutil cp gs://bucket1/* gs://bucket2

mas o comando a seguir copia apenas arquivos que não começam com . do diretório dir para gs://bucket1:

gsutil cp dir/* gs://bucket1

Análise da eficiência: como usar caracteres curingas em muitos objetos

É mais eficiente, mais rápido e ocupa menos a rede usar caracteres curinga com um prefixo de nome de objeto que não seja curinga, como:

gs://bucket/abc*.txt

do que usar curingas como a primeira parte do nome do objeto, como:

gs://bucket/*abc.txt

Isso ocorre porque a solicitação para gs://bucket/abc*.txt solicita que o servidor retorne o subconjunto de resultados com nomes de objeto que começam com abc na raiz do bucket e, em seguida, o gsutil filtra a lista de resultados dos objetos com um nome que termine com .txt. Por outro lado, o gs://bucket/*abc.txt pede ao servidor a lista completa de objetos na raiz do bucket e filtra esses objetos com o nome que termina com abc.txt. Essa consideração de eficiência se torna cada vez mais perceptível quando você usa buckets que contêm milhares (ou mais) de objetos. Às vezes, é possível configurar os nomes dos seus objetos para se ajustarem aos padrões esperados de correspondência de caracteres curinga para aproveitar a eficiência de fazer solicitações de prefixo do servidor. Consulte, por exemplo, gsutil help prod para um exemplo de caso de uso concreto.

Análise da eficiência: como usar caracteres curinga intermediários

Suponha que você tenha um bucket com estes objetos:

gs://bucket/obj1
gs://bucket/obj2
gs://bucket/obj3
gs://bucket/obj4
gs://bucket/dir1/obj5
gs://bucket/dir2/obj6

Se você executar o comando:

gsutil ls gs://bucket/*/obj5

O gsutil executará uma listagem de buckets de nível superior /-delimited e uma listagem de buckets para cada subdiretório, totalizando três listagens:

GET /bucket/?delimiter=/
GET /bucket/?prefix=dir1/obj5&delimiter=/
GET /bucket/?prefix=dir2/obj5&delimiter=/

Quanto mais listagens de bucket seu caractere curinga exigir, mais lento e mais caro será. O número de listagens de bucket necessárias aumenta dessa maneira:

  • o número de componentes com caracteres curinga (por exemplo, "gs://bucket/a? b/c*/*/d" tem três componentes curinga);
  • o número de subdiretórios que correspondem a cada componente; e
  • o número de resultados (a paginação é implementada usando uma solicitação GET por 1.000 resultados, especificando marcadores para cada um).

Se você quiser usar um curinga intermediário, em vez disso, prefira um curinga recursivo, por exemplo:

gsutil ls gs://bucket/**/obj5

Isso corresponde a mais objetos do que gs://bucket/*/obj5, já que abrange diretórios, mas é implementado usando uma solicitação de listagem de bucket sem delimitador, o que significa menos solicitações de bucket, mesmo que ele liste todo o bucket e os filtros localmente, de modo que isso possa exigir uma quantidade não trivial de tráfego de rede.