Criar buckets com namespace hierárquico ativado

Nesta página, descrevemos como criar buckets com o namespace hierárquico ativado.

Funções exigidas

Para receber a permissão necessária para criar um bucket com o namespace hierárquico ativado, peça ao administrador para conceder a você o papel do IAM de Administrador do Storage (roles/storage.admin) no projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esse papel predefinido contém a permissão storage.buckets.create, que é necessária para criar um bucket com o namespace hierárquico ativado.

Também é possível receber essa permissão com papéis personalizados ou outros papéis predefinidos.

Criar um bucket com namespace hierárquico ativado

Console

1. No console do Google Cloud , acesse a página Buckets do Cloud Storage.
   

   Acesse Buckets

2. Clique em Criar.

3. Na página Criar um bucket, insira as informações do seu bucket. Após cada uma das etapas a seguir, clique em Continuar para prosseguir para a próxima etapa:

   1. Na seção Começar, faça o seguinte:

      • Insira um nome globalmente exclusivo que atenda aos requisitos de nome de bucket.

   2. Na seção Escolha onde armazenar seus dados, faça o seguinte:

      1. Selecione um tipo de local.

      2. Use o menu suspenso do tipo de local para selecionar um Local em que os dados de objetos no bucket serão armazenados permanentemente.

         • Se você selecionar o tipo de local birregional, também poderá ativar a replicação turbo usando a caixa de seleção relevante.

   3. Na seção Escolha como armazenar seus dados, faça o seguinte:

      1. Selecione uma classe de armazenamento padrão para o bucket ou Classe automática para gerenciamento automático da classe de armazenamento dos dados do bucket.

      2. Na seção Otimizar o armazenamento para cargas de trabalho com uso intensivo de dados, faça o seguinte:

         • Para ativar o namespace hierárquico, selecione Ativar namespace hierárquico neste bucket.

           Observação:o namespace hierárquico só pode ser ativado ao criar o bucket. Não é possível mudar essa configuração depois de criar o bucket.

   4. Na seção Escolha como controlar o acesso a objetos, selecione se o bucket aplica ou não a prevenção de acesso público e selecione o acesso uniforme no nível do bucket para os objetos dele.

      Observação:se a prevenção de acesso público já estiver aplicada pela política da organização do projeto, a caixa de seleção Impedir acesso público estará bloqueada.

   5. Na seção Escolha como proteger os dados do objeto, faça o seguinte:

      • Selecione qualquer uma das opções em Proteção de dados que você quer definir para o bucket.

      • Para mudar o período em que a exclusão reversível mantém os objetos após a exclusão, marque a caixa de seleção Política de exclusão reversível e selecione a opção Definir duração personalizada da retenção. Em seguida, especifique por quanto tempo você quer reter objetos excluídos.

        Para desativar a exclusão reversível, por exemplo, se o bucket contiver principalmente dados temporários de curta duração, desmarque a caixa de seleção Política de exclusão reversível.

      • Para escolher como criptografar os dados do objeto, clique na seta de expansão identificada como Criptografia de dados e faça o seguinte:

        • Na seção Tipo de chave de criptografia padrão, selecione a chave de criptografia padrão do bucket. Se você selecionar Chave do Cloud KMS, forneça uma chave do Cloud Key Management Service.
        • Na seção Regras de aplicação de criptografia, em Tipos de chave, selecione quais tipos de criptografia permitir ou restringir para novos objetos no bucket.

4. Clique em Criar.

Para saber como acessar informações detalhadas de erro sobre operações do Cloud Storage com falha no Google Cloud console, consulte Solução de problemas.

Linha de comando

1. No console do Google Cloud , ative o Cloud Shell.

   Ativar o Cloud Shell

   Na parte de baixo do console Google Cloud , uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.

2. No ambiente de desenvolvimento, execute o comando gcloud storage buckets create:

   gcloud storage buckets create gs://BUCKET_NAME --location=BUCKET_LOCATION --uniform-bucket-level-access --enable-hierarchical-namespace

   Em que:

   • BUCKET_NAME é o nome que você quer dar ao bucket, sujeito a requisitos de nomenclatura. Exemplo:my-bucket
   • BUCKET_LOCATION é o local do bucket. Por exemplo, us-east1.
   • --uniform-bucket-level-access: ative o acesso uniforme no nível do bucket para seu bucket.
     
     Observação: é necessário ativar o acesso uniforme no nível do bucket em um bucket para criar um com namespace hierárquico ativado.
   • --enable-hierarchical-namespace: ative o namespace hierárquico do bucket. Não é possível ativar o namespace hierárquico em um bucket atual.

   Se a solicitação for bem-sucedida, o comando retornará a seguinte mensagem:

   Creating gs://BUCKET_NAME/...

   Para ter mais controle sobre a criação do bucket, defina as seguintes flags:

   • --project: especifique o ID ou número do projeto a que o bucket será associado. Por exemplo, my-project.
   • --default-storage-class: especifique a classe de armazenamento padrão do bucket. Por exemplo, STANDARD. Para gerenciar automaticamente as classes de armazenamento dos objetos, use a flag --enable-autoclass. Para mais informações, consulte Classe automática.

   Para uma lista completa de opções para criar buckets usando a CLI do Google Cloud, consulte buckets create opções.

   Por exemplo:

   gcloud storage buckets create gs://BUCKET_NAME --project=PROJECT_ID --default-storage-class=STORAGE_CLASS --location=BUCKET_LOCATION --uniform-bucket-level-access --enable-hierarchical-namespace

Bibliotecas de cliente

C++

Para mais informações, consulte a documentação de referência da API Cloud Storage C++.

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente.

namespace gcs = ::google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string const& bucket_name) {
  auto metadata = client.CreateBucket(
      bucket_name,
      gcs::BucketMetadata()
          .set_hierarchical_namespace(gcs::BucketHierarchicalNamespace{true})
          .set_iam_configuration(gcs::BucketIamConfiguration{
              gcs::UniformBucketLevelAccess{true, {}}, std::nullopt}));
  if (!metadata) throw std::move(metadata).status();

  std::cout << "Bucket " << metadata->name() << " created."
            << "\nFull Metadata: " << *metadata << "\n";
}

C#

Para mais informações, consulte a documentação de referência da API Cloud Storage C#.

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente.

using Google.Apis.Storage.v1.Data;
using Google.Cloud.Storage.V1;
using System;

public class CreateBucketWithHierarchicalNamespaceEnabledSample
{
    public Bucket CreateBucketWithHierarchicalNamespace(
        string projectId = "your-project-id",
        string bucketName = "your-unique-bucket-name")
    {
        var storage = StorageClient.Create();
        var bucket = storage.CreateBucket(projectId,
            new Bucket
            {
                Name = bucketName,
                IamConfiguration = new Bucket.IamConfigurationData
                {
                    UniformBucketLevelAccess = new Bucket.IamConfigurationData.UniformBucketLevelAccessData { Enabled = true }
                },
                HierarchicalNamespace = new Bucket.HierarchicalNamespaceData { Enabled = true }
            });
        Console.WriteLine($"Created {bucketName} with Hierarchical Namespace enabled.");
        return bucket;
    }
}

Go

Para mais informações, consulte a documentação de referência da API Cloud Storage Go.

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente.

import (
	"context"
	"fmt"
	"io"
	"time"

	"cloud.google.com/go/storage"
)

// createBucketHierarchicalNamespace creates a new bucket with hierarchical
// namespace features enabled.
func createBucketHierarchicalNamespace(w io.Writer, projectID, bucketName string) error {
	// projectID := "my-project-id"
	// bucketName := "bucket-name"

	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %w", err)
	}
	defer client.Close()

	ctx, cancel := context.WithTimeout(ctx, time.Second*30)
	defer cancel()

	attrs := &storage.BucketAttrs{
		HierarchicalNamespace: &storage.HierarchicalNamespace{
			Enabled: true,
		},
		// Hierarchical namespace buckets must use uniform bucket-level access.
		UniformBucketLevelAccess: storage.UniformBucketLevelAccess{
			Enabled: true,
		},
	}
	bucket := client.Bucket(bucketName)
	if err := bucket.Create(ctx, projectID, attrs); err != nil {
		return fmt.Errorf("Bucket(%q).Create: %w", bucketName, err)
	}
	fmt.Fprintf(w, "Created bucket %v with hierarchical namespace enabled\n", bucketName)
	return nil
}

Java

Para mais informações, consulte a documentação de referência da API Cloud Storage Java.

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente.

import com.google.cloud.storage.Bucket;
import com.google.cloud.storage.BucketInfo;
import com.google.cloud.storage.BucketInfo.HierarchicalNamespace;
import com.google.cloud.storage.BucketInfo.IamConfiguration;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

public final class CreateHierarchicalNamespaceBucket {

  public static void createHierarchicalNamespaceBucket(String projectId, String bucketName)
      throws Exception {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The ID to give your GCS bucket
    // String bucketName = "your-unique-bucket-name";
    StorageOptions storageOptions = StorageOptions.newBuilder().setProjectId(projectId).build();
    try (Storage storage = storageOptions.getService()) {

      BucketInfo bucketInfo =
          BucketInfo.newBuilder(bucketName)
              .setIamConfiguration(
                  // Hierarchical namespace buckets must use uniform bucket-level access.
                  IamConfiguration.newBuilder().setIsUniformBucketLevelAccessEnabled(true).build())
              .setHierarchicalNamespace(HierarchicalNamespace.newBuilder().setEnabled(true).build())
              .build();

      Bucket bucket = storage.create(bucketInfo);

      System.out.printf(
          "Created bucket %s with Hierarchical Namespace enabled.%n", bucket.getName());
    }
  }
}

Node.js

Para mais informações, consulte a documentação de referência da API Cloud Storage Node.js.

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente.

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The ID of your GCS bucket
// const bucketName = 'your-unique-bucket-name';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
// The bucket in the sample below will be created in the project associated with this client.
// For more information, please see https://cloud.google.com/docs/authentication/production or https://googleapis.dev/nodejs/storage/latest/Storage.html
const storage = new Storage();

async function createBucketWithHierarchicalNamespace() {
  const [bucket] = await storage.createBucket(bucketName, {
    iamConfiguration: {
      uniformBucketLevelAccess: {
        enabled: true,
      },
    },
    hierarchicalNamespace: {
      enabled: true,
    },
  });

  console.log(
    `Created '${bucket.name}' with hierarchical namespace enabled.`
  );
}

createBucketWithHierarchicalNamespace().catch(console.error);

PHP

Para mais informações, consulte a documentação de referência da API Cloud Storage PHP.

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente.

use Google\Cloud\Storage\StorageClient;

/**
 * Create a new bucket with Hierarchical Namespace enabled.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 *        (e.g. 'my-bucket')
 */
function create_bucket_hierarchical_namespace(string $bucketName): void
{
    $storage = new StorageClient();
    $bucket = $storage->createBucket($bucketName, [
        'hierarchicalNamespace' => ['enabled' => true],
        'iamConfiguration' => ['uniformBucketLevelAccess' => ['enabled' => true]]
    ]);

    printf('Created bucket %s with Hierarchical Namespace enabled.', $bucket->name());
}

Python

Para mais informações, consulte a documentação de referência da API Cloud Storage Python.

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente.

from google.cloud import storage


def create_bucket_hierarchical_namespace(bucket_name):
    """Creates a bucket with hierarchical namespace enabled."""
    # The ID of your GCS bucket
    # bucket_name = "your-bucket-name"

    storage_client = storage.Client()
    bucket = storage_client.bucket(bucket_name)
    bucket.iam_configuration.uniform_bucket_level_access_enabled = True
    bucket.hierarchical_namespace_enabled = True
    bucket.create()

    print(f"Created bucket {bucket_name} with hierarchical namespace enabled.")

Ruby

Para mais informações, consulte a documentação de referência da API Cloud Storage Ruby.

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente.

def create_bucket_hierarchical_namespace bucket_name:
  # The ID to give your GCS bucket
  # bucket_name = "your-unique-bucket-name"

  require "google/cloud/storage"

  storage = Google::Cloud::Storage.new

  hierarchical_namespace = Google::Apis::StorageV1::Bucket::HierarchicalNamespace.new enabled: true

  storage.create_bucket bucket_name do |b|
    b.uniform_bucket_level_access = true
    b.hierarchical_namespace = hierarchical_namespace
  end

  puts "Created bucket #{bucket_name} with Hierarchical Namespace enabled."
end

Rust

use google_cloud_storage::{
    client::StorageControl,
    model::Bucket,
    model::bucket::iam_config::UniformBucketLevelAccess,
    model::bucket::{HierarchicalNamespace, IamConfig},
};

pub async fn sample(
    client: &StorageControl,
    project_id: &str,
    bucket_id: &str,
) -> anyhow::Result<()> {
    let bucket = client
        .create_bucket()
        .set_parent("projects/_")
        .set_bucket_id(bucket_id)
        .set_bucket(
            Bucket::new()
                .set_project(format!("projects/{project_id}"))
                .set_hierarchical_namespace(HierarchicalNamespace::new().set_enabled(true))
                .set_iam_config(IamConfig::new().set_uniform_bucket_level_access(
                    UniformBucketLevelAccess::new().set_enabled(true),
                )),
        )
        .send()
        .await?;
    println!("successfully created bucket {bucket:?}");
    Ok(())
}

APIs REST

API JSON

1. Ter a CLI gcloud instalada e inicializada, o que permite gerar um token de acesso para o cabeçalho Authorization.

2. Crie um arquivo JSON com as configurações do bucket, incluindo um name para o bucket. Consulte a documentação Buckets: Insert para ver uma lista completa de configurações. Veja a seguir configurações comuns a serem incluídas:

{
  "name": "BUCKET_NAME",
  "location": "BUCKET_LOCATION",
  "storageClass": "STORAGE_CLASS",
  "hierarchicalNamespace": {
    "enabled": "BOOLEAN"
  },
  "iamConfiguration": {
    "uniformBucketLevelAccess": {
      "enabled": true
  },
},
}

Em que:

• BUCKET_NAME é o nome que você quer dar ao bucket, sujeito a requisitos de nomenclatura. Por exemplo, my-bucket.
• BUCKET_LOCATION é o local em que você quer armazenar os dados de objeto do intervalo. Por exemplo, US-EAST1.
• STORAGE_CLASS é a classe de armazenamento padrão do bucket. Por exemplo, STANDARD.
• hierarchicalNamespace.enabled está definido como TRUE para ativar o namespace hierárquico do bucket. Não é possível ativar o namespace hierárquico em um bucket atual.
3. uniformBucketLevelAccess.enabled é definido como TRUE para ativar o acesso uniforme no nível do bucket.
   
   Observação: é necessário ativar o acesso uniforme no nível do bucket em um bucket para criar um com namespace hierárquico ativado.
4. Use cURL para chamar a API JSON:

   curl -X POST --data-binary @JSON_FILE_NAME \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     "https://storage.googleapis.com/storage/v1/b?project=PROJECT_IDENTIFIER"

   Em que:

   • JSON_FILE_NAME é o nome do arquivo JSON que contém as configurações do bucket.
   • PROJECT_IDENTIFIER é o ID ou número do projeto ao qual o bucket será associado. Por exemplo, my-project.

A seguir

• Entender as pastas.
• Criar e gerenciar pastas.
• Acessar metadados de um bucket.
• Acesse o layout de armazenamento de um bucket.
• Listar e excluir buckets.

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