Sobre as pastas em buckets com namespace hierárquico ativado

Esta página fornece informações sobre pastas em buckets com namespace hierárquico ativado.

Visão geral

Ao criar um bucket com namespace hierárquico ativado, ele usa uma estrutura de sistema de arquivos real, em vez de um namespace simples padrão. As pastas existem como um recurso em buckets com namespace hierárquico ativado. Usando pastas, é possível organizar seus objetos com mais eficiência e ter acesso a recursos de diretório reais, como renomeações de pastas atômicas e operações de metadados eficientes.

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, bem como 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 Folder recurso em a 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 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

Esta seção descreve 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 dele, a pasta mãe ausente é criada automaticamente. Por exemplo, a criação de um objeto chamado dir1/foo.txt cria automaticamente a pasta dir1/ se ela ainda não existir.

Para informações sobre a nomenclatura de pastas, consulte Considerações.

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 de pastas real em vez de simular pastas de caminhos de objetos.

Ao listar pastas, é possível filtrar os resultados usando parâmetros como prefix, delimiter, lexicographicStart e lexicographicEnd. Por exemplo, definir o parâmetro de 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 metadados da 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 reside. Para uma lista detalhada das propriedades retornadas por essa operação, consulte Metadados da pasta.

Renomear ou mover uma pasta

A renomeação e a movimentação de uma pasta usam a mesma operação subjacente. 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. A renomeação de 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.

Durante uma operação de renomeação de pastas, é 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 ou comando de URL. No Google Cloud console, Renomear pasta e Mover pasta são apresentadas como duas opções distintas, mas ambas as opções 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 objetos, elas não são removidas automaticamente quando ficam vazias. É necessário excluí-las 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 namespace hierárquico ativado, todas as pastas ausentes no caminho dela são criadas automaticamente, incluindo 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 criará automaticamente a pasta mãe 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ê está excluindo 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 da pasta, a operação de exclusão da pasta 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.

Considerações

Ao criar pastas, considere o seguinte:

  • Nomes de objetos e pastas: buckets com namespace hierárquico ativado oferecem suporte a todos os nomes de objeto válidos, incluindo aqueles com barras iniciais e finais (/) ou barras consecutivas. Cada barra encaminhada (/) em um nome de objeto representa uma pasta. A tabela a seguir mostra exemplos da relação entre nomes de objetos e seu local correspondente na hierarquia de pastas:

    Nome do objeto Local na hierarquia de pastas
    foo.txt Todo bucket possui uma pasta raiz. O objeto foo.txt fica na pasta raiz do bucket.
    dir1/foo.txt O objeto foo.txt fica em uma pasta de nível superior chamada dir1/. A pasta de nível superior é diferente da pasta raiz.
    dir1/ A barra à direita em nomes de objetos, como dir1/ indica que o objeto está na pasta. Neste exemplo, o nome do objeto dir1/ é igual ao nome da pasta mãe dir1/.
    dir1//foo.txt O objeto foo.txt reside em uma pasta de segundo nível chamada dir1//, uma pasta filha de dir1/.

  • 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 só poderá ter até 15 pastas filhas empilhadas.

  • Tamanho máximo do nome da pasta: 512 bytes (codificados em UTF-8).

  • Informações de identificação pessoal (PII): os nomes de pastas são mais visíveis do que os metadados de pastas. 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 de pastas.

A seguir

Faça um teste

Se você começou a usar o Google Cloud agora, crie uma conta para avaliar o desempenho do Cloud Storage em situações reais. Clientes novos recebem US $300 em créditos para executar, testar e implantar cargas de trabalho.

Faça uma avaliação sem custo financeiro do Cloud Storage