Mantenha tudo organizado com as coleções
Salve e categorize o conteúdo com base nas suas preferências.
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.
?
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 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:
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.
[[["Fácil de entender","easyToUnderstand","thumb-up"],["Meu problema foi resolvido","solvedMyProblem","thumb-up"],["Outro","otherUp","thumb-up"]],[["Difícil de entender","hardToUnderstand","thumb-down"],["Informações incorretas ou exemplo de código","incorrectInformationOrSampleCode","thumb-down"],["Não contém as informações/amostras de que eu preciso","missingTheInformationSamplesINeed","thumb-down"],["Problema na tradução","translationIssue","thumb-down"],["Outro","otherDown","thumb-down"]],["Última atualização 2025-08-18 UTC."],[],[],null,["# URI wildcards\n\nThe [Google Cloud CLI](/sdk/gcloud/reference/storage) supports the use of URI wildcards for files, buckets,\nand objects. Wildcards allow you to efficiently work with groups of files that\nmatch specified naming patterns. This page describes the wildcards that are\nsupported and notes important considerations when using wildcards in commands.\n| **Note:** You cannot use the gcloud CLI to perform operations on folders that have wildcards in the folder's name. For example, you cannot use the gcloud CLI to list objects in the folder `gs://my-bucket/*my-folder/`, which contains the `*` wildcard. Instead, use the Google Cloud console.\n\nWildcard characters\n-------------------\n\nThe gcloud CLI supports the following wildcards:\n\nYou can combine wildcards to provide more powerful matches, for example: \n\n```\ngs://*/[a-m]??.j*g\n```\n\nNote that unless your command includes a flag to return\n[noncurrent object versions](/storage/docs/object-versioning) in the results, these wildcards only match live\nobject versions.\n\nThe gcloud CLI supports the same wildcards for both object and file\nnames. Thus, for example: \n\n```\ngcloud storage cp data/abc* gs://bucket\n```\n\nmatches all files that start with `abc` in the `data` directory of the local\nfile system.\n\nBehavior considerations\n-----------------------\n\nThere are several cases where using wildcards can result in surprising behavior:\n\n- When using wildcards in bucket names, matches are limited to buckets in a\n single [project](/storage/docs/projects). Many commands allow you to specify a project using a\n flag. If a command does not include a project flag or does not support the use\n of a project flag, matches are limited to buckets in the default project.\n\n- Shells (like bash and zsh) can attempt to expand wildcards before passing the\n arguments to the gcloud CLI. If the wildcard was supposed to refer\n to a cloud object, this can result in surprising \"Not found\" errors. For\n example, the shell might try to expand the wildcard `gs://my-bucket/*` on the\n local machine, which would match no local files, causing the command to fail.\n\n Additionally, some shells include other characters in their wildcard\n character sets. For example, if you use zsh with the extendedglob option\n enabled, it treats `#` as a special character, which conflicts with that\n character's use in referencing versioned objects (see\n [Restore noncurrent object versions](/storage/docs/using-versioned-objects#restore) for an example).\n\n To avoid these problems, surround the wildcarded expression with single\n quotes (on Linux) or double quotes (on Windows).\n- Attempting to specify a filename that contains wildcard characters won't work,\n because the command line tools try to expand the wildcard characters rather\n than using them as literal characters. For example, running the command:\n\n ```\n gcloud storage cp './file[1]' gs://my-bucket\n ```\n\n never copies a local file named `file[1]`. Instead, the\n gcloud CLI always treat the `[1]` as a wildcard.\n\n The gcloud CLI does not support a \"raw\" mode that allows it to\n work with file names that contain wildcard characters. For such files, you\n should either use a different tool such as the Google Cloud console or use\n a wildcard to capture the files. For example, to capture a file named\n `file[1]`, you could use the following command: \n\n ```\n gcloud storage cp './file*1*' gs://my-bucket\n ```\n- Per standard Unix behavior, the wildcard `*` only matches files that don't\n start with a `.` character (to avoid confusion with the `.` and `..`\n directories present in all Unix directories). The gcloud CLI\n provides this same behavior when using wildcards over a file system URI, but\n does not provide this behavior over cloud URIs. For example, the following\n command copies all objects from `gs://bucket1` to `gs://bucket2`:\n\n ```\n gcloud storage cp gs://bucket1/* gs://bucket2\n ```\n\n However, the following command copies only files that don't start with a\n `.` from the directory `dir` to `gs://bucket1`: \n\n ```\n gcloud storage cp dir/* gs://bucket1\n ```\n\nEfficiency considerations\n-------------------------\n\n- It is more efficient, faster, and less network traffic-intensive to use\n wildcards that have a non-wildcard object-name prefix, such as:\n\n ```\n gs://bucket/abc*.txt\n ```\n\n than it is to use wildcards as the first part of the object name, such as: \n\n ```\n gs://bucket/*abc.txt\n ```\n\n This is because the request for `gs://bucket/abc*.txt` asks the server to\n send back the subset of results whose object name start with `abc` at the\n bucket root, and then filters the result list for objects whose name ends\n with `.txt`. In contrast, `gs://bucket/*abc.txt` asks the server for the\n complete list of objects in the bucket root, and then filters for those\n objects whose name ends with `abc.txt`. This efficiency consideration\n becomes increasingly noticeable when you use buckets containing thousands or\n more objects. It is sometimes possible to set up the names of your objects\n to fit with expected wildcard matching patterns to take advantage of the\n efficiency of doing server-side prefix requests.\n- Suppose you have a bucket with these objects:\n\n ```\n gs://bucket/obj1\n gs://bucket/obj2\n gs://bucket/obj3\n gs://bucket/obj4\n gs://bucket/dir1/obj5\n gs://bucket/dir2/obj6\n ```\n\n If you run the command: \n\n ```\n gcloud storage ls gs://bucket/*/obj5\n ```\n\n `gcloud storage` performs a `/`-delimited top-level bucket listing and then\n one bucket listing for each subdirectory, for a total of 3 bucket listings: \n\n ```\n GET /bucket/?delimiter=/\n GET /bucket/?prefix=dir1/obj5&delimiter=/\n GET /bucket/?prefix=dir2/obj5&delimiter=/\n ```\n\n The more bucket listings your wildcard requires, the slower and more\n expensive it becomes. The number of bucket listings required grows as:\n - the number of wildcard components (e.g., `gs://bucket/a??b/c*/*/d` has 3\n wildcard components);\n\n - the number of subdirectories that match each component; and\n\n - the number of results (pagination is implemented when the number of\n results is too large, specifying markers for each).\n\n If you want to use a mid-path wildcard, you might try instead using a\n recursive wildcard, for example: \n\n ```\n gcloud storage ls gs://bucket/**/obj5\n ```\n\n This matches more objects than `gs://bucket/*/obj5` (since it spans\n directories), but is implemented using a delimiter-less bucket listing\n request (which means fewer bucket requests, though it lists the entire\n bucket and filters locally, so that could require a non-trivial amount of\n network traffic)."]]
