Caracteres curinga de URI

A CLI do Google Cloud é compatível com o uso de caracteres curinga de URI para arquivos, buckets e objetos. Com os caracteres curinga, é possível trabalhar de maneira eficiente com grupos de arquivos que correspondem a padrões de nomenclatura específicos. Nesta página, descrevemos os caracteres curinga compatíveis e mostramos considerações importantes ao usar caracteres curinga em comandos.

Caracteres curinga

A CLI gcloud é compatível com os seguintes caracteres curinga:

Caractere	Descrição
`*`	Corresponde a zero ou mais caracteres no nível de diretório atual. Por exemplo, `cp gs://my-bucket/abc/d` corresponde ao objeto `abc/def.txt`, mas não ao objeto `abc/def/g.txt`. No caso de comandos de listagem como `ls`, se um `` à direita corresponder a um subdiretório no nível de diretório atual, o conteúdo do subdiretório também será listado.
`**`	Corresponde a zero ou mais caracteres nos limites do 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. Observação: alguns shells de comando expandem correspondências de caracteres curinga antes de executar o comando gsutil. No entanto, a maioria dos shells não é compatível com caracteres curinga recursivos (``). É possível ignorar a expansão de caracteres curinga do shell do comando e usar o gcloud CLI e o suporte a caracteres curinga do gsutil nesses shells usando aspas simples (no Linux) ou duplas (no Windows). Exemplo: `gcloud storage cp 'data/**' gs://bucket`
`?`	Corresponde a um único caractere. Por exemplo, `gs://bucket/??.txt` corresponde apenas a objetos com dois caracteres seguidos por `.txt`.
`[CHARACTERS]`	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`.
`[CHARACTER_RANGE]`	Corresponde a qualquer um dos intervalos de caracteres. Por exemplo, `gs://bucket/[a-e].txt` corresponde a objetos que contêm as letras a, b, c, d ou e seguidas por `.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 CLI gcloud é compatível com os mesmos caracteres curingas para nomes de objetos e arquivos. Assim, por exemplo:

gcloud storage cp data/abc* gs://bucket

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

Considerações sobre comportamento

Há vários casos em que o uso de caracteres curinga pode resultar em um comportamento surpreendente:

Ao usar caracteres curingas em nomes de bucket, as correspondências são limitadas a buckets em um único projeto. Muitos comandos permitem que você especifique um projeto usando uma sinalização. Se um comando não incluir uma sinalização de projeto ou não oferecer suporte ao uso de uma sinalização de projeto, as correspondências serão limitadas a buckets no projeto padrão.
Os shells (como bash e zsh) podem tentar expandir caracteres curinga antes de transmitir os argumentos à gcloud CLI. Se o caractere curinga tiver que se referir a um objeto na nuvem, isso pode resultar em erros surpreendentes de "Não encontrado". Por exemplo, o shell pode tentar expandir o caractere curinga gs://my-bucket/* na máquina local, o que não corresponderia a nenhum arquivo local, fazendo com que o comando falhasse.

Além disso, alguns shells incluem outros caracteres 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).
Não é possível especificar um nome de arquivo que contenha caracteres curinga, porque as ferramentas de linha de comando tentam expandir os caracteres curinga em vez de usá-los como caracteres literais. Por exemplo, execute o comando:
```
gcloud storage cp './file[1]' gs://my-bucket
```
nunca copia um arquivo local chamado file[1]. Em vez disso, a CLI gcloud sempre trata o [1] como um caractere curinga.

A CLI gcloud não é compatível com um modo "bruto" que permite trabalhar com nomes de arquivo que contêm caracteres curinga. Para esses arquivos, use uma ferramenta diferente, como o Console do Google Cloud, ou use um caractere curinga para capturar os arquivos. Por exemplo, para capturar um arquivo chamado file[1], use o seguinte comando:
```
gcloud storage cp './file*1*' gs://my-bucket
```
Por comportamento padrão do Unix, o caractere curinga * corresponde apenas 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 CLI da gcloud oferece esse mesmo comportamento ao usar caracteres curinga em um URI do sistema de arquivos, mas não oferece esse mesmo comportamento em relação a URIs da nuvem. Por exemplo, o comando a seguir copia todos os objetos de gs://bucket1 para gs://bucket2:
```
gcloud storage cp gs://bucket1/* gs://bucket2
```
No entanto, o comando a seguir copia apenas arquivos que não começam com . do diretório dir para gs://bucket1:
```
gcloud storage cp dir/* gs://bucket1
```

Considerações sobre eficiência

É 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 caracteres curinga 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.
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:
```
gcloud storage ls gs://bucket/*/obj5
```
O gcloud storage executará uma / listagem de buckets de nível superior delimitada 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 quando o número de resultados é muito grande, especificando marcadores para cada solicitação).
Se você quiser usar um curinga intermediário, em vez disso, prefira um curinga recursivo, por exemplo:
```
gcloud storage 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.