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

Nesta página, você encontra informações sobre pastas em buckets com o namespace hierárquico ativado.

Visão geral

Ao criar um bucket com o 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. Com as pastas, você organiza seus objetos com mais eficiência e tem acesso a recursos de diretório reais, como renomeações atômicas de pastas 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 pastas, consulte Tipos de pastas.

É possível gerenciar pastas realizando operações de pastas. 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 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, criar um objeto chamado dir1/foo.txt cria automaticamente a pasta dir1/ se ela ainda não existir.

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

Listar pastas

Para extrair uma lista de pastas no seu bucket, use 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 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 estão 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 "get folder metadata". 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

Renomear e mover uma pasta usam a mesma operação. A operação é uma mudança atômica, apenas de metadados, que atualiza o caminho da pasta sem copiar ou excluir fisicamente os objetos subjacentes. Ao renomear uma pasta, o caminho dela também é atualizado para recursos dentro dela, 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 de URL ou comando. No console Cloud de Confiance , 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 uma pasta permanentemente usando a operação de exclusão. As pastas podem ser criadas automaticamente durante as operações de objetos, mas 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 namespace hierárquico ativado, todas as pastas ausentes no caminho são criadas automaticamente, incluindo pastas mãe e a pasta de destino real (também conhecida como pasta associada).

Por exemplo, imagine que você criou 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 acontece 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 os 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 requisitos de nomenclatura de pastas associadas a uma pasta gerenciada, 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. É possível criar pastas com até 50 pastas filhas aninhadas (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 aninhadas.
Tamanho máximo do nome da pasta: 512 bytes (codificados em UTF-8).
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.