O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Sobre as pastas em buckets com namespace hierárquico ativado

Quando você cria um bucket com o namespace hierárquico ativado, ele armazena dados em uma estrutura de sistema de arquivos real, em vez de um namespace simples padrão. As pastas em buckets com namespace hierárquico ativado permitem organizar objetos usando diretórios, incluindo recursos como renomeações atômicas de pastas. Neste documento, descrevemos os metadados e as operações de pastas, como elas interagem com as pastas gerenciadas e as considerações para usá-las.

As pastas em buckets com namespace hierárquico ativado são diferentes das pastas simuladas e gerenciadas. As pastas simuladas existem em buckets de namespace simples, e as pastas gerenciadas podem ser aplicadas em buckets de namespace simples e em buckets com namespace hierárquico ativado. As pastas gerenciadas são usadas principalmente para conceder permissões do IAM a grupos de objetos. Para mais informações sobre esses outros tipos de pasta, consulte Tipos de pasta.

É possível gerenciar pastas realizando operações de pasta. Para saber como criar, listar e excluir pastas, além de receber metadados de pastas, consulte Criar e gerenciar pastas. Para saber como renomear ou mover uma pasta, consulte Renomear uma pasta.

Metadados da pasta

Os metadados de uma pasta contêm informações estruturadas sobre ela. Para informações detalhadas sobre metadados de pasta, consulte o recurso Folder na documentação de referência da API JSON do Cloud Storage.

Os principais componentes dos metadados de uma pasta são:

bucket: o nome do bucket em que a pasta está. Por exemplo, my-bucket.
id: um identificador exclusivo da pasta no bucket. Por exemplo, hns-bucket/dir1/.
kind: o tipo de recurso. Para uma pasta, esse valor é sempre storage#folder.
name: o nome da pasta. Por exemplo, dir1/.
selfLink: um URL que faz referência à pasta na API Storage do Cloud Storage.
timeCreated: o carimbo de data/hora em que a pasta foi criada. Por exemplo, 2023-05-05T16:32:08.878000+00:00.
updated: o carimbo de data/hora da última atualização do recurso. Por exemplo, 2024-05-06T16:32:08.878000+00:00.

Operações de pasta

Nesta seção, descrevemos as operações que podem ser realizadas em pastas. Algumas operações iniciam uma operação de longa duração que pode ser monitorada para acompanhar o progresso e o status da operação.

Criar uma pasta

É possível criar pastas explicitamente usando a operação de criação de pastas. Além disso, quando você cria um objeto e especifica uma pasta inexistente no caminho, a pasta mãe ausente é criada automaticamente. Por exemplo: criar um objeto chamado dir1/foo.txt cria automaticamente a pasta dir1/, se ela ainda não existir.

Para informações sobre como nomear pastas, consulte Diretrizes para nomear pastas.

Listar pastas

É possível recuperar uma lista de pastas no bucket usando a operação de listagem de pastas. Como as pastas são recursos distintos em buckets com namespace hierárquico ativado, essa operação avalia a estrutura real da pasta, em vez de simular pastas de caminhos de objeto.

Ao listar pastas, é possível filtrar os resultados usando parâmetros como prefix, delimiter, lexicographicStart e lexicographicEnd. Por exemplo, definir o parâmetro delimitador como / permite listar pastas em um modo semelhante a um diretório, retornando apenas as pastas que correspondem ao prefixo ou que existem um nível abaixo dele.

A operação de listagem de pastas retorna resultados paginados. Uma única página de resposta pode conter no máximo 1.000 pastas.

Receber os metadados de uma pasta

É possível recuperar as propriedades de uma pasta usando a operação de recebimento de metadados de pasta. Essa operação recupera informações sobre o recurso de pasta em si, e não sobre os objetos que ele contém.

Essa operação retorna os metadados de uma pasta, que fornecem informações estruturadas, como o carimbo de data/hora de criação, o identificador exclusivo e o bucket em que ela está. Para uma lista detalhada das propriedades retornadas por essa operação, consulte Metadados da pasta.

Renomear ou mover uma pasta

Renomear e mover uma pasta usam a mesma operação. A operação é uma mudança atômica, somente de metadados, que atualiza o caminho da pasta sem copiar ou excluir fisicamente os objetos subjacentes. Renomear uma pasta também atualiza o caminho dela para recursos dentro da pasta, como pastas filhas, objetos e pastas gerenciadas. Isso torna a operação rápida e evita custos de cópia de objetos.

A operação de renomeação de pasta inicia uma operação de longa duração. O tempo que a operação leva para ser concluída depende do número de pastas que ela renomeia, incluindo a pasta em si e todas as pastas filhas. Para acompanhar o progresso de uma operação de renomeação de pasta, consulte Usar operações de longa duração. Durante uma operação de renomeação de pasta, é possível ler e listar as pastas que estão sendo renomeadas, mas não é possível executar operações de gravação nelas.

Na API JSON e na Google Cloud CLI, as operações de renomeação e movimentação usam o mesmo endpoint de URL ou comando. No console do Google Cloud , Renomear pasta e Mover pasta são apresentadas como duas opções distintas, mas ambas executam a mesma operação de back-end.

excluir uma pasta

É possível excluir permanentemente uma pasta usando a operação de exclusão de pasta. Embora as pastas possam ser criadas automaticamente durante as operações de objeto, elas não são removidas automaticamente quando ficam vazias. É preciso excluí-los explicitamente.

Interações entre pastas e pastas gerenciadas associadas

As pastas gerenciadas associadas são usadas para controlar o acesso a pastas em buckets com namespace hierárquico ativado. As pastas e as pastas gerenciadas associadas interagem das seguintes maneiras:

Criação de pastas: quando você cria uma pasta gerenciada em um bucket com o namespace hierárquico ativado, todas as pastas ausentes no caminho são criadas automaticamente, incluindo as pastas mãe e a pasta de destino real (também conhecida como pasta associada).

Por exemplo, digamos que você crie um bucket com namespace hierárquico ativado chamado my-bucket. Se você criar uma pasta gerenciada chamada 2025/training-data/ no bucket, o Cloud Storage vai criar automaticamente a pasta pai 2025/ e a pasta associada de destino training-data/ no bucket.
Exclusão de pastas: quando você exclui uma pasta que tem uma pasta gerenciada associada, o Cloud Storage também exclui a pasta gerenciada associada. Isso ocorre porque, ao excluir uma pasta, você exclui o caminho inteiro. Como o caminho não existe mais, a pasta gerenciada associada e todas as políticas do IAM anexadas a ela são excluídas. Em buckets com namespace hierárquico ativado, uma pasta gerenciada não pode existir sem uma pasta associada.

Se você não tiver as permissões necessárias para excluir a pasta gerenciada associada, a operação de exclusão da pasta vai falhar. Para encontrar as permissões necessárias para excluir pastas gerenciadas, consulte Receber papéis necessários para pastas gerenciadas.
Renomeação de pastas: quando você renomeia uma pasta que tem uma pasta gerenciada associada, o Cloud Storage também renomeia a pasta gerenciada associada.

Para informações sobre os requisitos de nomenclatura de pastas que têm uma pasta gerenciada associada, consulte Nomenclatura de pastas.

Diretrizes de nomenclatura de pastas

Ao criar pastas, consulte as seguintes diretrizes:

A relação entre nomes de objetos e nomes de pastas: em buckets com namespace hierárquico ativado, pastas e objetos são recursos distintos, mesmo que o nome de um objeto inclua o caminho da pasta. O nome de um objeto é sempre o caminho completo dentro do bucket (como dir1/foo.txt), enquanto cada barra (/) atua como um delimitador que coloca o objeto dentro de um recurso de pasta (como dir1/).

Os buckets com namespace hierárquico ativado aceitam todos os nomes de objeto válidos, incluindo aqueles com barras iniciais, finais ou consecutivas. Quando você faz upload de um objeto, o Cloud Storage cria automaticamente todos os recursos de pasta ausentes no caminho dele.

A tabela a seguir mostra como os nomes de objetos são mapeados para recursos de pasta:

Nome do objeto	Pasta mãe	Local na hierarquia de pastas
`foo.txt`	Pasta raiz	Todo bucket tem uma pasta raiz sem nome. Como `foo.txt` não contém barra, o objeto reside diretamente na pasta raiz.
`dir1/foo.txt`	`dir1/`	O nome completo do objeto é `dir1/foo.txt`, não `foo.txt`. Ele reside na pasta de nível superior `dir1/`, que é diferente da pasta raiz.
`dir1/`	`dir1/`	Uma barra à direita não transforma um objeto em uma pasta. Em vez disso, um objeto chamado `dir1/` é um recurso de objeto separado que reside na pasta `dir1/`.
`/foo.txt`	`/`	Uma barra inicial define uma pasta de nível superior chamada `/`, que é diferente da pasta raiz. O objeto `/foo.txt` está na pasta `/`.
`dir1//foo.txt`	`dir1//`	Barras consecutivas definem pastas aninhadas. O objeto `dir1//foo.txt` reside na pasta de segundo nível `dir1//`, que é filha de `dir1/`.

Informações de identificação pessoal (PII): os nomes das pastas são mais visíveis do que os metadados delas. Por exemplo, os nomes de pastas aparecem em URLs e ao listar pastas ou objetos em um bucket. Não inclua informações sensíveis ou PII nos nomes das pastas.
Tamanho máximo do nome da pasta: 512 bytes (codificação UTF-8).
Profundidade máxima da pasta: buckets com namespace hierárquico ativado dão suporte a uma profundidade de pasta máxima de 50. As pastas podem ser criadas com até 50 pastas filhas empilhadas (por exemplo, folder1/folder2/folder3/.../folder50/my-data.txt). No entanto, se uma pasta tiver uma pasta gerenciada associada, ela poderá ter apenas até 15 pastas filhas empilhadas.

Sobre as pastas em buckets com namespace hierárquico ativado Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.