Todos os produtos
Search
Central de documentação

Object Storage Service:PutBucketLifecycle

Última atualização: Oct 16, 2026

Crie regras de ciclo de vida com base na data da última modificação ou do último acesso. Essas regras convertem periodicamente a classe de armazenamento dos objetos em um bucket ou excluem objetos e partes expirados, reduzindo os custos de armazenamento. Este tópico descreve como chamar a operação PutBucketLifecycle para configurar uma regra de ciclo de vida em um bucket.

Observações

  • A operação PutBucketLifecycle sobrescreve as regras de ciclo de vida existentes. Por exemplo, se um bucket possui uma regra de ciclo de vida chamada Rule1 e você deseja adicionar uma regra chamada Rule2, execute as seguintes etapas:

    1. Chame a operação GetBucketLifecycle para obter a configuração da Rule1.

    2. Inclua a Rule2 junto com a Rule1.

    3. Chame a operação PutBucketLifecycle para aplicar a nova configuração que inclui tanto a Rule1 quanto a Rule2.

  • Defina um tempo de expiração para objetos e partes. As partes são fragmentos não confirmados de uploads multipart.

  • Configure a correspondência das regras com base na hora do último acesso ou da última modificação.

  • Após ativar a opção NOT, não é possível configurar uma política de expiração de partes nem remover marcadores de exclusão de objetos.

Permissões

Por padrão, uma conta Alibaba Cloud tem permissões totais. Usuários RAM ou funções RAM sob 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 do RAM policies ou Bucket Policy.

API

Ação

Descrição

PutBucketLifecycle

oss:PutBucketLifecycle

Configura regras de ciclo de vida para um bucket.

Sintaxe da requisição

PUT /?lifecycle HTTP/1.1
Date: GMT Date
Content-Length: ContentLength
Content-Type: application/xml
Authorization: SignatureValue 
Host: BucketName.oss.aliyuncs.com
<?xml version="1.0" encoding="UTF-8"?>
<LifecycleConfiguration>
  <Rule>
    <ID>RuleID</ID>
    <Prefix>Prefix</Prefix>
    <Status>Status</Status>
    <Expiration>
      <Days>Days</Days>
    </Expiration>
    <Transition>
      <Days>Days</Days>
      <StorageClass>StorageClass</StorageClass>
    </Transition>
    <AbortMultipartUpload>
      <Days>Days</Days>
    </AbortMultipartUpload>
  </Rule>
</LifecycleConfiguration>

Cabeçalhos da requisição

Nome

Tipo

Obrigatório

Exemplo

Descrição

x-oss-allow-same-action-overlap

string

Não

true

Especifica se permite que as regras de ciclo de vida tenham prefixos sobrepostos. Valores válidos:

  • true: Prefixos sobrepostos são permitidos.

  • false: Prefixos sobrepostos não são permitidos.

Esta operação usa cabeçalhos de requisição comuns, como Date e Authorization. Para mais informações, consulte Common request headers.

Elementos da requisição

Nome

Tipo

Obrigatório

Exemplo

Descrição

LifecycleConfiguration

contêiner

Sim

N/A

O contêiner para configurações de ciclo de vida. Você pode configurar até 1.000 regras.

Nó filho: Rule

Nó pai: None

Rule

contêiner

Sim

N/A

O contêiner para uma regra de ciclo de vida. O tempo de expiração de um objeto deve ser posterior ao tempo em que o objeto é convertido para a classe de armazenamento Infrequent Access (IA) ou Archive Storage.

Nós filhos: ID, Prefix, Status e Expiration

Nó pai: LifecycleConfiguration

ID

string

Não

rule1

O ID exclusivo da regra. O ID pode ter até 255 caracteres. Se você não especificar este elemento ou deixá-lo vazio, o OSS gera automaticamente um ID exclusivo.

Nó filho: None

Nó pai: Rule

Prefix

string

Não

tmp/

O prefixo que especifica os objetos aos quais a regra se aplica. Você não pode definir o mesmo prefixo para regras diferentes.

  • Se você especificar Prefix, a regra se aplica apenas aos objetos no bucket que possuem o prefixo especificado.

  • Se você deixar Prefix vazio, a regra se aplica a todos os objetos no bucket.

Nó filho: None

Nó pai: Rule

Status

string

Sim

Enabled

Especifica se deve ativar a regra. Valores válidos:

  • Enabled: A regra está ativada. O OSS executa a regra periodicamente.

  • Disabled: A regra está desativada. O OSS ignora a regra.

Nó pai: Rule

Expiration

contêiner

Não

N/A

Especifica as propriedades de expiração de um objeto. Para um bucket com versionamento ativado, o tempo de expiração especificado se aplica apenas à versão atual de um objeto.

O tempo de expiração de um objeto deve ser posterior ao tempo em que o objeto é convertido para a classe de armazenamento IA ou Archive Storage.

Nós filhos: Days, CreatedBeforeDate ou ExpiredObjectDeleteMarker

Nó pai: Rule

Days

Inteiro positivo

Days e CreatedBeforeDate são mutuamente exclusivos

1

Especifica o número de dias após a última atualização de um objeto em que a regra de ciclo de vida entra em vigor.

Se o parâmetro IsAccessTime estiver definido como true na requisição, este parâmetro especifica o número de dias após o último acesso de um objeto em que a regra de ciclo de vida entra em vigor.

Nós pais: Expiration ou AbortMultipartUpload

CreatedBeforeDate

string

CreatedBeforeDate e Days são mutuamente exclusivos

2002-10-11T00:00:00.000Z

Especifica uma data. O OSS aplica a regra de ciclo de vida aos dados que foram atualizados pela última vez antes dessa data. A data deve estar no formato yyyy-MM-ddT00:00:00.000Z.

A data deve estar em UTC e em conformidade com o padrão ISO 8601. A hora deve ser 00:00:00.

Nós pais: Expiration ou AbortMultipartUpload

ExpiredObjectDeleteMarker

string

Não

true

Especifica se deve remover automaticamente os marcadores de exclusão expirados. Valores válidos:

  • true: Remove automaticamente os marcadores de exclusão expirados. Se você definir este valor como true, não poderá especificar Days ou CreatedBeforeDate.

  • false: Não remove automaticamente os marcadores de exclusão expirados. Se você definir este valor como false, deverá especificar Days ou CreatedBeforeDate.

Nó pai: Expiration

Transition

contêiner

Não

N/A

Especifica quando o OSS converte a classe de armazenamento de um objeto durante seu ciclo de vida válido.

Você pode converter objetos Standard em um bucket Standard para a classe de armazenamento IA, Archive ou Cold Archive. No entanto, o tempo para converter para Archive deve ser posterior ao tempo para converter para IA. Por exemplo, se você definir Days como 30 para a transição para IA, deverá definir Days com um valor maior que 30 para a transição para Archive.

Nó pai: Rule

Nós filhos: Days, CreatedBeforeDate e StorageClass

Importante
Importante

Você pode especificar Days ou CreatedBeforeDate.

StorageClass

string

Obrigatório se o nó pai for Transition ou NoncurrentVersionTransition

IA

Especifica a classe de armazenamento para a qual um objeto é convertido. Valores válidos:

  • IA: Infrequent Access

  • Archive: Archive Storage

  • ColdArchive: Cold Archive

  • DeepColdArchive: Deep Cold Archive

Importante

Você pode converter a classe de armazenamento de objetos em um bucket IA para Archive Storage ou Cold Archive, mas não para Standard.

Nó pai: Transition

AbortMultipartUpload

contêiner

Não

N/A

Especifica as propriedades de expiração para partes que não são confirmadas em um upload multipart.

Nós filhos: Days ou CreatedBeforeDate

Nó pai: Rule

Tag

contêiner

Não

N/A

As tags de objeto às quais a regra se aplica. Você pode especificar várias tags.

Nó pai: Rule

Nós filhos: Key e Value

Key

string

Obrigatório se o nó pai for Tag

TagKey1

A chave da tag do objeto.

Nó pai: Tag

Value

string

Obrigatório se o nó pai for Tag

TagValue1

O valor da tag do objeto.

Nó pai: Tag

NoncurrentVersionExpiration

contêiner

Não

N/A

Especifica as propriedades de expiração para versões anteriores de objetos.

Nó filho: NoncurrentDays

NoncurrentVersionTransition

contêiner

Não

N/A

Especifica quando o OSS converte a classe de armazenamento de versões anteriores de um objeto para IA ou Archive Storage.

O tempo para converter um objeto Standard para Archive deve ser posterior ao tempo para convertê-lo para IA.

Nós filhos: NoncurrentDays e StorageClass

NoncurrentDays

string

Obrigatório se o nó pai for NoncurrentVersionExpiration ou NoncurrentVersionTransition

10

Especifica o número de dias após um objeto se tornar uma versão anterior em que a regra de ciclo de vida entra em vigor.

Se o parâmetro IsAccessTime estiver definido como true na requisição, este parâmetro especifica o número de dias após o último acesso de um objeto em que a regra de ciclo de vida entra em vigor.

Nós pais: NoncurrentVersionTransition e NoncurrentVersionExpiration

IsAccessTime

string

Não

true

Especifica se deve corresponder à regra com base na hora do último acesso. Valores válidos:

  • true: Corresponde à regra com base na hora do último acesso de um objeto.

  • false (padrão): Corresponde à regra com base na hora da última modificação de um objeto.

Nós pais: Transition ou NoncurrentVersionTransition.

ReturnToStdWhenVisit

string

Não

false

Especifica se deve converter a classe de armazenamento de um objeto não Standard para Standard quando o objeto for acessado novamente. Este parâmetro é válido apenas quando IsAccessTime está definido como true. Valores válidos:

  • true: A classe de armazenamento do objeto é convertida para Standard.

  • false (padrão): A classe de armazenamento do objeto permanece não Standard.

Nós pais: Transition ou NoncurrentVersionTransition.

AllowSmallFile

string

Não

false

Ao definir uma regra de ciclo de vida com base na hora do último acesso, este parâmetro especifica se deve converter objetos menores que 64 KB para a classe de armazenamento IA, Archive ou Cold Archive. Valores válidos:

  • true (padrão): Converte todos os objetos, incluindo aqueles menores que 64 KB. Objetos menores que 64 KB são cobrados como 64 KB. Objetos com 64 KB ou mais são cobrados com base em seu tamanho real. Definir este parâmetro como true pode aumentar suas taxas de armazenamento.

  • false: Não converte objetos menores que 64 KB.

Nós pais: Transition ou NoncurrentVersionTransition.

Filter

contêiner

Não

N/A

O contêiner para os parâmetros de condição desta regra de exclusão. Este parâmetro pode estar vazio.

Nó pai: Rule

Nó filho: Not

Not

contêiner

Não

N/A

Se um objeto atender a esta condição, a regra será ignorada.

Importante

As regras de ciclo de vida agora suportam a configuração de múltiplos elementos NOT. Este recurso está em visualização por convite e ainda não está disponível para todos os usuários. Para solicitar acesso, entre em contato com o suporte técnico. Um único bucket pode conter até 1.000 elementos NOT, uma única regra pode conter até 100 elementos NOT e todas as regras podem conter até 2.000 elementos Prefix no total.

Nó pai: Filter

Nós filhos: Prefix e Tag

Prefix

string

Sim

tmp/not/

O prefixo do objeto ao qual esta regra de exclusão se aplica. Este parâmetro não pode estar vazio.

  • Se você configurar Prefix no nó Rule, o Prefix no nó Not deve começar com o Prefix do nó Rule. Por exemplo, se o Prefix no nó Rule for dir, o Prefix no nó Not deve começar com dir, como dir1 ou dir2.

  • Se você não configurar Tag no nó Not, o Prefix no nó Not não pode ser igual ao Prefix no nó Rule.

Nó pai: Not

Nó filho: None

Tag

contêiner

Não

N/A

A tag do objeto à qual esta regra de exclusão se aplica. Você pode especificar no máximo uma tag ou deixar este parâmetro vazio.

ObjectSizeGreaterThan

Inteiro positivo

Não

500

O tamanho mínimo do objeto ao qual esta regra se aplica. Este parâmetro é opcional e você pode especificar no máximo um. Se você também definir ObjectSizeLessThan, o sistema verifica a relação de tamanho entre os dois.

Este parâmetro é mutuamente exclusivo com AllowSmallFile.

Nó pai: Filter

Nó filho: None

ObjectSizeLessThan

Inteiro positivo

Não

64000

O tamanho máximo do objeto ao qual esta regra se aplica. Este parâmetro é opcional e você pode especificar no máximo um. Se você também definir ObjectSizeGreaterThan, o sistema verifica a relação de tamanho entre os dois.

Este parâmetro é mutuamente exclusivo com AllowSmallFile.

Nó pai: Filter

Nó filho: None

Cabeçalhos da resposta

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

Exemplos

Exemplos de requisição

Exemplo 1: Converter a classe de armazenamento de objetos com base na hora da última modificação

No exemplo a seguir, a classe de armazenamento de objetos com o prefixo log é convertida para IA 30 dias após a hora da última modificação.

PUT /?lifecycle HTTP/1.1
Host: oss-example.oss.aliyuncs.com
Content-Length: 336
Date: Mon, 6 May 2019 15:23:20 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
<?xml version="1.0" encoding="UTF-8"?>
<LifecycleConfiguration>
  <Rule>
    <ID>rule</ID>
    <Prefix>log/</Prefix>
    <Status>Enabled</Status>
    <Transition>
      <Days>30</Days>
      <StorageClass>IA</StorageClass>
    </Transition>    
  </Rule>
</LifecycleConfiguration>

Exemplo 2: Excluir objetos com base na hora da última modificação

No exemplo a seguir, objetos com o prefixo log são excluídos 90 dias após a hora da última modificação.

PUT /?lifecycle HTTP/1.1
Host: oss-example.oss.aliyuncs.com
Content-Length: 336
Date: Thu, 17 Apr 2025 15:23:20 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
<?xml version="1.0" encoding="UTF-8"?>
<LifecycleConfiguration>
  <Rule>
    <ID>rule</ID>
    <Prefix>log/</Prefix>
    <Status>Enabled</Status>
    <Expiration>
      <Days>90</Days>
    </Expiration>    
 </Rule>
</LifecycleConfiguration>

Exemplo 3: Converter a classe de armazenamento de objetos e excluí-los com base na hora da última modificação

A regra a seguir executa estas ações em objetos com o prefixo log: converte sua classe de armazenamento para IA 30 dias após a última modificação, converte para Archive Storage após 60 dias e os exclui após 3.600 dias.

PUT /?lifecycle HTTP/1.1
Host: oss-example.oss.aliyuncs.com
Content-Length: 336
Date: Thu, 17 Apr 2025 15:23:20 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
<?xml version="1.0" encoding="UTF-8"?>
<LifecycleConfiguration>
  <Rule>
    <ID>rule</ID>
    <Prefix>log/</Prefix>
    <Status>Enabled</Status>
    <Transition>
      <Days>30</Days>
      <StorageClass>IA</StorageClass>
    </Transition>
    <Transition>
      <Days>60</Days>
      <StorageClass>Archive</StorageClass>
    </Transition>
    <Expiration>
      <Days>3600</Days>
    </Expiration>
  </Rule>
</LifecycleConfiguration>

Exemplo 4: Excluir versões anteriores de objetos e limpar marcadores de exclusão com base na hora da última modificação

A regra a seguir exclui objetos 5 dias após eles se tornarem versões anteriores e limpa os marcadores de exclusão após todas as versões anteriores serem excluídas.

PUT /?lifecycle HTTP/1.1
Host: oss-example.oss.aliyuncs.com
Content-Length: 336
Date: Thu, 17 Apr 2025 15:23:20 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
<?xml version="1.0" encoding="UTF-8"?>
<LifecycleConfiguration>
  <Rule>
    <ID>rule</ID>
    <Prefix></Prefix>
    <Status>Enabled</Status>
    <Expiration>
      <ExpiredObjectDeleteMarker>true</ExpiredObjectDeleteMarker>
    </Expiration>
    <NoncurrentVersionExpiration>
      <NoncurrentDays>5</NoncurrentDays>
    </NoncurrentVersionExpiration>    
  </Rule>
</LifecycleConfiguration>

Exemplo 5: Converter a classe de armazenamento de objetos e excluí-los com base na hora da última modificação, excluindo objetos com um prefixo e tag específicos

A regra a seguir usa o elemento NOT para filtragem. Esta regra se aplica a todos os objetos no bucket, exceto àqueles que possuem o prefixo 'log' e a tag Key=key1, Value=value1. A classe de armazenamento dos objetos correspondentes é convertida para Archive Storage 30 dias após a última modificação, e os objetos são excluídos após 100 dias.

PUT /?lifecycle HTTP/1.1
Host: oss-example.oss.aliyuncs.com
Content-Length: 336
Date: Thu, 17 Apr 2025 15:23:20 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
<?xml version="1.0" encoding="UTF-8"?>
<LifecycleConfiguration>
  <Rule>
    <ID>rule</ID>
    <Prefix></Prefix>
    <Status>Enabled</Status>
    <Filter>
      <Not>
        <Prefix>log</Prefix>
        <Tag><Key>key1</Key><Value>value1</Value></Tag>
      </Not>
    </Filter>    
    <Transition>
      <Days>30</Days>
      <StorageClass>Archive</StorageClass>
    </Transition>
    <Expiration>
      <Days>100</Days>
    </Expiration>
  </Rule>
</LifecycleConfiguration>

Exemplo 6: Converter a classe de armazenamento de objetos com base na hora do último acesso

A regra a seguir converte a classe de armazenamento de objetos com o prefixo log para IA 30 dias após a hora do último acesso. Quando esses objetos são acessados novamente, sua classe de armazenamento é convertida de volta para Standard.

PUT /?lifecycle HTTP/1.1
Host: oss-example.oss.aliyuncs.com
Content-Length: 336
Date: Thu, 17 Apr 2025 15:23:20 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
<?xml version="1.0" encoding="UTF-8"?>
<LifecycleConfiguration>
  <Rule>
    <ID>rule</ID>
    <Prefix>log/</Prefix>
    <Status>Enabled</Status>
    <Transition>
      <Days>30</Days>
      <StorageClass>IA</StorageClass>
      <IsAccessTime>true</IsAccessTime>
      <ReturnToStdWhenVisit>true</ReturnToStdWhenVisit>
    </Transition>
  </Rule>
</LifecycleConfiguration>

Exemplo 7: Excluir partes com base na hora da última modificação

A regra a seguir exclui partes em um bucket que foram criadas há mais de 30 dias.

PUT /?lifecycle HTTP/1.1
Host: oss-example.oss.aliyuncs.com
Content-Length: 336
Date: Thu, 17 Apr 2025 15:23:20 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
<?xml version="1.0" encoding="UTF-8"?>
<LifecycleConfiguration>
  <Rule>
    <ID>rule</ID>
    <Prefix>/</Prefix>
    <Status>Enabled</Status>    
    <AbortMultipartUpload>
      <Days>30</Days>
    </AbortMultipartUpload>
 </Rule>
</LifecycleConfiguration>

Exemplo 8: Excluir objetos com prefixos sobrepostos com base na hora da última modificação

A regra a seguir especifica que os objetos na pasta dir1/ são excluídos 180 dias após a última modificação, e os objetos na subpasta dir1/dir2/ são excluídos 30 dias após a última modificação.

PUT /?lifecycle HTTP/1.1
Host: oss-example.oss.aliyuncs.com
Content-Length: 336
Date: Thu, 17 Apr 2025 15:23:20 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
x-oss-allow-same-action-overlap: true
<?xml version="1.0" encoding="UTF-8"?>
<LifecycleConfiguration>
  <Rule>
    <ID>Rule1</ID>
    <Prefix>dir1/</Prefix>
    <Status>Status</Status>
    <Expiration>
      <Days>180</Days>
    </Expiration>
  </Rule>
  <Rule>
    <ID>Rule2</ID>
    <Prefix>dir1/dir2/</Prefix>
    <Status>Status</Status>
    <Expiration>
      <Days>30</Days>
    </Expiration>
  </Rule>
</LifecycleConfiguration>
Nota

Se x-oss-allow-same-action-overlap estiver definido como false, o OSS detecta que os objetos na pasta dir1/dir2/ correspondem a duas regras de exclusão. Nesse caso, o OSS rejeita a configuração dessas duas regras de ciclo de vida e relata o erro Overlap for same action type Expiration.

Exemplo de resposta

HTTP/1.1 200 OK
x-oss-request-id: 7D3435J59A9812BAD56E
Date: Mon, 6 May 2019 15:23:20 GMT
Content-Length: 0
Connection: keep-alive
Server: AliyunOSS

SDK

Você pode chamar esta operação usando os kits de desenvolvimento de software (SDKs) das seguintes linguagens de programação.

Ferramenta de linha de comando ossutil

Para obter informações sobre o comando do ossutil correspondente à operação PutBucketLifecycle, consulte put-bucket-lifecycle.

Referências

Para mais informações sobre as regras de ciclo de vida, consulte Lifecycle rule overview.

Códigos de erro

Código de erro

Código de status HTTP

Descrição

InvalidArgument

400

Possíveis causas para este erro:

  • O OSS permite a conversão de objetos Standard em um bucket Standard para a classe de armazenamento IA ou Archive Storage. É possível configurar regras para converter um objeto para IA e Archive Storage em momentos diferentes, mas o momento da conversão para Archive Storage deve ser posterior ao da conversão para IA.

  • A data de expiração de um objeto deve ser posterior ao momento da conversão do objeto para a classe de armazenamento IA ou Archive Storage.

AccessDenied

403

Você não tem as permissões necessárias. Somente usuários com a permissão oss:PutBucketLifecycle podem configurar regras de ciclo de vida.

MalforedXML

400

Um erro de validação de XML na configuração de ciclo de vida resulta no erro MalformedXML. Por exemplo, esse erro ocorre se você configurar uma regra de ciclo de vida com base no último horário de acesso de um bucket antes que você ative o rastreamento de acesso para o bucket.