Pastas simuladas

Nesta página, você encontra uma visão geral das pastas no Cloud Storage.

Informações gerais das pastas

Com exceção das pastas gerenciadas, o Cloud Storage opera com um namespace simples. Isso significa que as pastas não existem no Cloud Storage. Se você criar um objeto chamado folder1/file.txt no bucket your-bucket, o caminho para o objeto será your-bucket/folder1/file.txt, mas não haverá uma pasta chamada folder1. Em vez disso, a string folder1 fará parte do nome do objeto.

No entanto, o console do Google Cloud e as CLIs do Cloud Storage fornecem a ilusão de uma árvore de arquivos hierárquica:

  • O console do Google Cloud cria uma representação visual de pastas semelhantes a um navegador de arquivos local.

  • As CLIs do Cloud Storage simulam a experiência típica do diretório de linha de comando usando várias regras.

/storage/images/folders.svg

Ferramentas

Clique nas guias abaixo para ver como cada ferramenta lida com pastas.

Console

No console do Google Cloud, é possível criar uma pasta vazia em um bucket ou fazer upload de uma pasta existente.

Quando você faz upload de uma pasta existente, o nome dela se torna parte do caminho de todos os objetos contidos nela. Todas as subpastas e os objetos que elas contêm também são incluídos no upload.

Para criar uma pasta:

  1. No Console do Cloud, acesse a página Buckets do Cloud Storage.

    Acessar buckets

  2. Navegue até o bucket.

  3. Clique em Criar pasta para criar uma nova pasta vazia ou em Fazer upload de pasta para fazer upload de uma pasta existente.

Linha de comando

Para alcançar a ilusão de uma árvore de arquivos hierárquica, os comandos gcloud storage e gsutil aplicarão as seguintes regras para determinar se a URL de destino em um comando será tratada como um nome de objeto ou pasta:

  1. Se a URL de destino terminar com um caractere /, os comandos da CLI tratarão a URL de destino como uma pasta. Por exemplo, considere o seguinte comando, em que your-file é o nome de um arquivo:

    gcloud storage cp your-file gs://your-bucket/abc/

    Como resultado desse comando, o Cloud Storage cria um objeto chamado abc/your-file no bucket your-bucket.

  2. Se você copiar vários arquivos de origem para uma URL de destino, as CLIs tratarão a URL de destino como uma pasta. Por exemplo, considere o comando a seguir, em que your-dir é uma pasta contendo arquivos como file1 e file2:

    gcloud storage cp your-dir gs://your-bucket/abc --recursive

    Como resultado desse comando, o Cloud Storage cria os objetos abc/your-dir/file1 e abc/your-dir/file2 no bucket your-bucket.

  3. Se nenhuma das regras acima se aplicar, as CLIs verificarão os objetos no bucket para determinar se a URL de destino é um nome de objeto ou uma pasta. Por exemplo, considere o seguinte comando, em que your-file é o nome de um arquivo:

    gcloud storage cp your-file gs://your-bucket/abc

    A CLI faz uma solicitação de listagem de objetos para your-bucket, usando o delimitador / e prefixo=abc, para determinar se há objetos em your-bucket com caminhos começando com abc/. Nesse caso, a CLI trata abc/ como um nome de pasta, e o comando acima cria o objeto abc/your-file no bucket your-bucket. Caso contrário, a CLI criará o objeto abc em your-bucket.

Essa abordagem baseada em regras difere da maneira como muitas ferramentas funcionam, que criam objetos de 0 byte para marcar a existência de pastas. As CLIs do Cloud Storage entendem várias convenções usadas por essas ferramentas, como a convenção de adicionar _$folder$ ao final do nome do objeto de 0 byte, mas as CLIs não exigem esses objetos de marcador para implementar o comportamento de nomenclatura consistente com os comandos UNIX.

Novas tentativas e nomenclatura

Quando uma CLI do Cloud Storagerepete uma solicitação interrompida, você poderá encontrar um problema em que a primeira tentativa copia um subconjunto de arquivos e as tentativas subsequentes encontram uma pasta de destino já existente, o que faz com que os objetos sejam nomeados incorretamente.

Por exemplo, considere o comando a seguir, em que há subpastas em your-dir/, como dir1 e dir2, e as duas subpastas contêm o arquivo abc:

gcloud storage cp ./your-dir gs://your-bucket/new --recursive

Se o caminho gs://your-bucket/new ainda não existir, as CLIs criarão os seguintes objetos na primeira tentativa bem-sucedida:

new/dir1/abc
new/dir2/abc

No entanto, na próxima tentativa bem-sucedida do mesmo comando, as CLIs criarão os seguintes objetos:

new/your-dir/dir1/abc
new/your-dir/dir2/abc

Para que as CLIs funcionem de maneira consistente em todas as tentativas, tente o seguinte:

  1. Adicione uma barra ao final da URL de destino para que as CLIs sempre a tratem como uma pasta.

  2. Use gcloud storage rsync ou gsutil rsync. Como rsync não usa as regras de nomenclatura de pastas definidas pelo comando cp do Unix, ele funciona de maneira consistente, independentemente de a subpasta de destino existir ou não.

Para mais informações sobre como os nomes são construídos, consulte construção de nomes usando cp.

Outras observações

  • Não é possível criar um objeto de zero byte para imitar uma pasta vazia usando as CLIs do Cloud Storage.

  • Se você usar scripts para criar caminhos de arquivo combinando subcaminhos, observe que, como / é apenas um caractere que está no nome do objeto, as CLIs interpretarão gs://my-bucket/folder/ para ser um objeto diferente de gs://my-bucket//folder.

APIs REST

API JSON

Não há pastas na API JSON. Para restringir os objetos que você lista, use os parâmetros de consulta prefix e delimiter.

Por exemplo, para listar todos os objetos no bucket my-bucket com o prefixo folder/subfolder/, faça uma solicitação de listagem de objetos usando este URL:

"https://storage.googleapis.com/storage/v1/b/my-bucket/o?prefix=folder/subfolder/"

API XML

As pastas não existem na API XML, mas é possível restringir os objetos listados usando os parâmetros de consulta prefix e delimiter.

Por exemplo, para listar todos os objetos no bucket my-bucket com o prefixo folder/subfolder/, faça uma solicitação de listagem de objetos usando este URL:

"https://storage.googleapis.com/my-bucket?prefix=folder/subfolder/"

A seguir