Pastas

Nesta página, você conhecerá as pastas do Cloud Storage e como elas variam de acordo com as ferramentas do Cloud Storage.

Visão geral

O Cloud Storage opera com um namespace simples, o que 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 a gsutil dão 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.
A gsutil simula a experiência típica do diretório da 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:

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

Acessar buckets
Navegue até o bucket.
Clique em Criar pasta para criar uma nova pasta vazia ou em Fazer upload de pasta para fazer upload de uma pasta existente.

gsutil

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

Se o URL de destino terminar com um caractere /, a gsutil tratará o URL de destino como uma pasta. Por exemplo, considere o seguinte comando, em que your-file é o nome de um arquivo:
```
gsutil cp your-file gs://your-bucket/abc/
```
Como resultado, a gsutil cria um objeto chamado gs://your-bucket/abc/your-file.
Se você copiar vários arquivos de origem para um URL de destino, a gsutil tratará o 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:
```
gsutil cp -r your-dir gs://your-bucket/abc
```
Como resultado, a gsutil cria os objetos gs://your-bucket/abc/your-dir/file1 e gs://your-bucket/abc/your-dir/file2.
Se nenhuma das regras acima se aplicar, a gsutil verificará os objetos no bucket para determinar se o 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:
```
gsutil cp your-file gs://your-bucket/abc
```
A gsutil faz uma solicitação de listagem de objetos para your-bucket, usando o delimitador / e prefixo=abc, para determinar se há objetos no bucket cujo caminho começa com gs://your-bucket/abc/. Nesse caso, a gsutil trata gs://your-bucket/abc como um nome de pasta, e o comando acima cria o objeto gs://your-bucket/abc/your-file. Caso contrário, a gsutil criará o objeto gs://your-bucket/abc.

A abordagem baseada em regras da gsutil é diferente da maneira como muitas ferramentas funcionam, que criam objetos de 0 byte para marcar a existência de pastas. A gsutil entende 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 a gsutil não exige esses objetos de marcador para implementar o comportamento de nomenclatura consistente com os comandos UNIX.

Novas tentativas e nomenclatura

Se você ativar tentativas automáticas usando a gsutil, poderá ocorrer um problema em que uma primeira tentativa só copia um subconjunto de arquivos e as tentativas subsequentes encontram uma pasta de destino que já existe e nomeam os objetos 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:

gsutil cp -r ./your-dir gs://your-bucket/new

Se gs://your-bucket/new ainda não existir, a gsutil criará os seguintes objetos na primeira tentativa bem-sucedida:

gs://your-bucket/new/dir1/abc
gs://your-bucket/new/dir2/abc

Na próxima tentativa bem-sucedida, a gsutil criará os seguintes objetos:

gs://your-bucket/new/your-dir/dir1/abc
gs://your-bucket/new/your-dir/dir2/abc

Para que a gsutil funcione de maneira consistente em todas as tentativas, faça o seguinte:

Adicione uma barra no final do URL de destino para que a gsutil sempre o trate como uma pasta.
Use gsutil rsync. Como o 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.
Se a gsutil rsync não funcionar para você, crie um objeto de marcador para estabelecer que o destino é uma pasta. Exemplo:
```
gsutil cp some-file gs://your-bucket/new/placeholder
```
Com o objeto de marcador presente, a execução do comando gsutil cp -r acima trata gs://your-bucket/new como uma pasta. Depois de ter pelo menos um dos objetos em gs://your-bucket/new, é possível excluir o objeto de marcador e continuar os uploads.

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

Observações adicionais

Não é possível criar um objeto de zero byte para imitar uma pasta vazia usando a gsutil.
Se você usar scripts para criar caminhos de arquivo combinando subcaminhos, observe que, como / é apenas um caractere que está no nome do objeto, a gsutil interpretará gs://my-bucket/folder/ para ser um objeto diferente de gs://my-bucket//folder.

Considerações de preço

Uma desvantagem da abordagem de nomenclatura da gsutil é que ela exige uma listagem de objetos extra antes de executar um comando cp ou mv, como uma cópia recursiva de uma pasta na nuvem. No entanto, essas listagens são relativamente baratas, porque usam os parâmetros delimiter e prefix para limitar os dados do resultado. A gsutil também faz apenas uma solicitação de listagem de objetos por comando cp ou mv e, portanto, elimina o custo de todos os objetos transferidos.

APIs REST

API JSON

Não existem pastas na API JSON, mas você pode 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/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

Upload de objetos para um bucket do Cloud Storage.