Algumas ou todas as informações nesta página podem não se aplicar ao Cloud de Confiance da S3NS. Consulte Diferenças do Google Cloud para saber mais.

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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.

É possível gerenciar pastas usando as operações de criação, exclusão, renomeação, listagem e recebimento. Para saber como realizar essas operações, consulte Criar e gerenciar pastas e Renomear uma pasta.

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.

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.

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 da pasta em si, e não sobre os objetos que ela 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.

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

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.

A operação de renomeação de pasta inicia uma operação de longa duração.

excluir uma pasta

É possível excluir permanentemente uma pasta vazia 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.

Se você excluir uma pasta que tenha uma pasta gerenciada no mesmo caminho, a pasta gerenciada também será excluída.

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. Como resultado, os nomes de objetos não podem ter mais de 50 barras (/).
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 confidenciais ou PII nos nomes de pastas.
Interação com pastas gerenciadas: em buckets com namespace hierárquico ativado, é possível gerenciar o controle de acesso usando pastas gerenciadas em conjunto com pastas.