Todos os produtos
Search

Este produto

    Object Storage Service:PutBucket

    Central de documentação

    Object Storage Service:PutBucket

    Última atualização: Oct 13, 2026

    Chame a operação PutBucket para criar um bucket.

    Observações

    • Uma conta Alibaba Cloud pode criar no máximo 100 buckets em cada região.

    • Cada região possui um endpoint correspondente. Para mais informações sobre os endpoints de cada região, consulte Endpoints.

    • Se você chamar a operação PutBucket várias vezes para o mesmo bucket, a primeira chamada cria o bucket e as chamadas subsequentes modificam seus metadados, como a ACL do bucket. Isso pode causar a sobrescrita dos metadados do bucket. Proceda com cautela.

    • A partir das 10:00:00 (UTC+8) de 13 de outubro de 2025, o OSS ativará gradualmente o bloqueio de acesso público por padrão para buckets criados por chamadas de API ou usando SDKs do OSS ou ossutil em todas as regiões. Para verificar quando a alteração entrará em vigor em cada região, consulte Announcement.

    Permissões

    Por padrão, uma conta Alibaba Cloud tem permissões totais. Usuários RAM ou funções RAM vinculados a uma conta Alibaba Cloud não possuem nenhuma permissão por padrão. A conta Alibaba Cloud ou o administrador da conta deve conceder permissões de operação por meio de RAM policies ou Bucket Policy.

    API

    Action

    Descrição

    PutBucket

    oss:PutBucket

    Cria um bucket.

    oss:PutBucketAcl

    Após criar um bucket, esta permissão é necessária para modificar a ACL do bucket.

    Sintaxe da solicitação

    PUT / HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
x-oss-acl: Permission
Authorization: SignatureValue
<?xml version="1.0" encoding="UTF-8"?>
<CreateBucketConfiguration>
    <StorageClass>Standard</StorageClass>
</CreateBucketConfiguration>

    Cabeçalhos da solicitação

    Nome

    Tipo

    Obrigatório

    Exemplo

    Descrição

    bucket

    String

    Sim

    examplebucket

    O nome do bucket. As convenções de nomenclatura para um bucket são as seguintes:

    • O nome pode conter apenas letras minúsculas, dígitos e hifens (-).

    • O nome deve começar e terminar com uma letra minúscula ou um dígito.

    • O nome deve ter entre 3 e 63 caracteres.

    x-oss-acl

    String

    Não

    private

    A lista de controle de acesso (ACL) do bucket. Valores válidos:

    • public-read-write: Concede permissões públicas de leitura e gravação.

    • public-read: Leitura pública

    • private (padrão)

    Para mais informações sobre ACLs de bucket, consulte Set bucket ACLs.

    x-oss-resource-group-id

    String

    Não

    rg-aek27tc****

    O ID do grupo de recursos.

    • Se você incluir este cabeçalho na solicitação e especificar um ID de grupo de recursos, o bucket criado pertencerá ao grupo de recursos especificado.

      Se você definir o ID do grupo de recursos como rg-default-id, o bucket criado pertencerá ao grupo de recursos padrão.

    • Caso este cabeçalho não seja incluído na solicitação, o bucket criado pertencerá ao grupo de recursos padrão.

    Obtenha o ID do grupo de recursos no console Resource Management ou chamando a operação ListResourceGroups. Para mais informações, consulte View resource groups e ListResourceGroups.

    x-oss-bucket-tagging

    String

    Não

    k1=v1&k2=v2

    Especifica as tags do bucket.

    x-oss-hns-status

    String

    Não

    disabled

    Define se o recurso de namespace hierárquico será ativado para o bucket.

    Ative o recurso de namespace hierárquico apenas durante a criação do bucket. Não é possível alterar o estado do namespace hierárquico de um bucket existente.

    • enabled: Ativado

      Após ativar o recurso de namespace hierárquico para um bucket, execute operações de diretório no bucket, como criar, excluir e renomear diretórios.

    • disabled (padrão): O recurso está desativado.

    x-oss-server-side-encryption

    String

    Não

    AES256

    Define o método padrão de criptografia no lado do servidor.

    Valores válidos: KMS, AES256

    Nota

    Em cenários de OSS no CloudBox, apenas AES256 é suportado.

    O uso do recurso KMS gera uma pequena taxa para chamadas de API do KMS. Para mais informações sobre preços, consulte KMS pricing.

    Durante a replicação entre regiões, se o bucket de destino tiver a criptografia padrão no lado do servidor ativada e a regra de replicação estiver configurada com um ReplicaCMKID, aplicam-se as seguintes situações:

    • Se um objeto no bucket de origem não estiver criptografado, ele será criptografado usando o método de criptografia padrão do bucket de destino após a replicação.

    • Caso um objeto no bucket de origem esteja criptografado com SSE-KMS ou SSE-OSS, o objeto manterá seu método de criptografia original no bucket de destino.

    Para mais informações, consulte Cross-region replication with server-side encryption.

    x-oss-server-side-encryption-key-id

    String

    Não

    9468da86-3509-4f8d-a61e-6eab1eac****

    O ID da chave KMS. Este cabeçalho é necessário apenas quando x-oss-server-side-encryption está definido como KMS. Em outros casos, este cabeçalho deve estar vazio.

    Este parâmetro não é suportado no OSS no CloudBox.

    Esta operação também inclui cabeçalhos de solicitação comuns. Para mais informações, consulte Common request headers.

    Elementos da solicitação

    Nome

    Tipo

    Obrigatório

    Exemplo

    Descrição

    StorageClass

    String

    Não

    Standard

    A classe de armazenamento do bucket. Valores válidos:

    • Standard (padrão)

    • IA: Acesso Infrequente

    • Archive: Armazenamento de Arquivo

    • ColdArchive: Cold Archive

    • DeepColdArchive: Deep Cold Archive

    Nó pai: CreateBucketConfiguration

    Nós filhos: Nenhum

    DataRedundancyType

    String

    Não

    LRS

    O tipo de redundância de dados do bucket. Valores válidos:

    • LRS (padrão)

      O armazenamento localmente redundante (LRS) armazena cópias dos seus dados em diferentes dispositivos de armazenamento na mesma zona. Isso garante durabilidade e disponibilidade dos dados mesmo que dois dispositivos de armazenamento sejam danificados simultaneamente.

    • ZRS

      O armazenamento com redundância de zona (ZRS) usa um mecanismo de redundância de dados em várias zonas. O ZRS armazena os dados de um objeto em várias zonas na mesma região. Se uma zona ficar indisponível, você ainda poderá acessar os dados.

    Nó pai: CreateBucketConfiguration

    Nós filhos: Nenhum

    Cabeçalhos da resposta

    Nome

    Tipo

    Exemplo

    Descrição

    Location

    String

    /oss-example

    O endereço do bucket. O valor é uma barra (/) seguida pelo nome do bucket.

    Valor padrão: Nenhum

    A resposta também inclui cabeçalhos de resposta comuns. Para mais informações, consulte Common response headers.

    Exemplos

    • Criar um bucket no grupo de recursos padrão

      HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906****
Date: Fri, 24 Feb 2017 03:15:40 GMT
Content-Length: 0
Connection: keep-alive
Server: AliyunOSS
Location: /oss-example

    • Exemplo de resposta

      HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906****
Date: Fri, 24 Feb 2017 03:15:40 GMT
Content-Length: 0
Connection: keep-alive
Server: AliyunOSS
Location: /oss-example

    • Criar um bucket em um grupo de recursos específico

      Exemplo de solicitação

      HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906****
Date: Fri, 24 Feb 2017 03:15:40 GMT
Content-Length: 0
Connection: keep-alive
Server: AliyunOSS
Location: /oss-example

      Exemplo de resposta

      HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906****
Date: Fri, 24 Feb 2017 03:15:40 GMT
Content-Length: 0
Connection: keep-alive
Server: AliyunOSS
Location: /oss-example

    SDK

    Chame a operação PutBucket usando os SDKs do OSS para as seguintes linguagens de programação:

    Ferramenta de linha de comando ossutil

    Para informações sobre o comando ossutil correspondente à operação PutBucket, consulte put-bucket.

    Códigos de erro

    Código de erro

    Código de status HTTP

    Descrição

    InvalidBucketName

    400

    O nome do bucket não está em conformidade com as convenções de nomenclatura.

    AccessDenied

    403

    As possíveis causas do erro incluem:

    • As informações de autenticação do usuário não foram incluídas na solicitação PutBucket.

    • Você não tem as permissões necessárias.

    TooManyBuckets

    400

    O número de buckets criados excede o limite superior. Uma conta Alibaba Cloud pode criar no máximo 100 buckets na mesma região.

    BucketAlreadyExists

    409

    • Se um bucket foi excluído, o requisito de tempo para criar um bucket com o mesmo nome não foi atendido.

      Você tentou criar um bucket com um nome que foi usado por um bucket excluído recentemente. Após a exclusão de um bucket, aguarde algumas horas (geralmente de 4 a 8 horas) antes de criar um bucket com o mesmo nome.

    • Você chamou a operação PutBucket usando métodos como usuário RAM ou STS para criar um bucket com o mesmo nome de um bucket existente.

      Apenas a conta Alibaba Cloud original pode recriar um bucket com o mesmo nome.

    • Você não tem permissões para chamar a operação PutBucketAcl. Verifique se o chamador recebeu a permissão oss:PutBucketAcl por meio de uma política de bucket ou uma política RAM.

    • Você tentou alterar o estado do namespace hierárquico de um bucket existente. Ative o recurso de namespace hierárquico apenas durante a criação do bucket.