Define uma política de retenção para uma versão específica de objeto e impede sua exclusão ou modificação até uma data determinada. Essa operação é fundamental em cenários de conformidade que exigem imutabilidade de dados. As políticas de retenção no nível do objeto substituem a política de retenção do bucket e permitem controle granular sobre objetos individuais.
Observações de uso
Atualmente, esse recurso está disponível apenas mediante convite. Para solicitar acesso, entre em contato com o suporte técnico.
Antes de chamar esta operação, ative o ObjectWorm (Write Once Read Many) no bucket por meio da operação
PutBucketObjectWormConfiguration. Se o ObjectWorm não estiver ativado, a solicitação falhará com o erroInvalidRequest.Para executar esta operação, você precisa da permissão
oss:PutObjectRetention. É possível conceder essa permissão por meio de políticas do RAM ou políticas de bucket.No modo de conformidade, o valor de
RetainUntilDatesó pode ser estendido, nunca reduzido. Tentar definir uma data anterior à data de retenção atual resulta no erroAccessDenied, o que garante a imutabilidade dos dados para fins de conformidade.As políticas de retenção definidas no nível do objeto por esta operação têm precedência sobre a política de retenção do bucket. Isso possibilita aplicar requisitos de retenção mais rigorosos a objetos específicos e manter uma política padrão para o bucket.
Objetos anexáveis não suportam políticas de retenção. A tentativa de configurar tal política em um objeto anexável causa falha na solicitação.
O valor de
RetainUntilDatedeve corresponder a uma data futura. O sistema rejeita datas passadas ou atuais.As políticas de retenção funcionam em conjunto com o versionamento. Se nenhum
versionIdfor especificado, a política será aplicada à versão atual (mais recente) do objeto. Para proteger versões específicas, inclua o ID da versão na solicitação.Durante o período de retenção, as versões protegidas do objeto não podem ser excluídas, sobrescritas ou ter sua retenção encurtada — nem mesmo pela conta raiz. Planeje os períodos de retenção com cuidado, pois eles não podem ser desfeitos no modo de conformidade.
Sintaxe da solicitação
PUT /ObjectName?retention HTTP/1.1
Content-MD5: ContentMD5
Content-Length: ContentLength
Content-Type: application/xml
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValueParâmetros da solicitação
|
Parâmetro |
Tipo |
Obrigatório |
Exemplo |
Descrição |
|
retention |
N/A |
Sim |
N/A |
Indica que a operação configura uma política de retenção de objeto. Este parâmetro de consulta é obrigatório para identificar a operação de retenção. |
|
versionId |
String |
Não |
CAEQNhiBgMDJgZCA0BYiIDc4MGZj**** |
O ID da versão do objeto. Se este parâmetro não for especificado, a operação será aplicada à versão mais recente do objeto. |
Cabeçalhos da solicitação
|
Cabeçalho |
Tipo |
Obrigatório |
Exemplo |
Descrição |
|
Content-MD5 |
String |
Sim |
B2M2Y8AsgTpgAmY7PhC**** |
O hash MD5 do corpo da solicitação. Este cabeçalho serve para verificar a integridade dos dados. |
Elementos do corpo da solicitação
|
Elemento |
Tipo |
Obrigatório |
Exemplo |
Descrição |
|
Retention |
Container |
Sim |
N/A |
O contêiner da política de retenção do objeto. Pai: Nenhum Filhos: Mode, RetainUntilDate |
|
Mode |
String |
Sim |
COMPLIANCE |
O modo de retenção do objeto. Valor válido:
Pai: Retention |
|
RetainUntilDate |
String |
Sim |
2026-10-11T00:00:00.000Z |
A data limite de retenção do objeto. O valor deve ser uma data no formato ISO 8601. Antes dessa data, a versão do objeto não pode ser excluída ou sobrescrita. A data especificada deve estar no futuro. No modo de conformidade, essa data só pode ser estendida, nunca reduzida. Pai: Retention |
Cabeçalhos da resposta
|
Cabeçalho |
Exemplo |
Descrição |
|
x-oss-version-id |
CAEQNhiBgMDJgZCA0BYiIDc4MGZj**** |
O ID da versão do objeto à qual a política de retenção se aplica. |
Exemplos
Exemplo 1: Defina uma política de retenção no modo de conformidade
-
Solicitação de exemplo
PUT /exampleobject?retention&versionId=CAEQNhiBgMDJgZCA0BYiIDc4MGZj**** HTTP/1.1 Date: Thu, 17 Mar 2026 11:18:32 GMT Content-MD5: B2M2Y8AsgTpgAmY7PhC**** Content-Type: application/xml Content-Length: 162 Host: examplebucket.oss-cn-hangzhou.aliyuncs.com Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20260317/cn-hangzhou/oss/aliyun_v4_request,Signature=**** <Retention> <Mode>COMPLIANCE</Mode> <RetainUntilDate>2026-10-11T00:00:00.000Z</RetainUntilDate> </Retention> -
Resposta de exemplo
HTTP/1.1 200 OK x-oss-request-id: 5374A2880232A65C2300**** x-oss-version-id: CAEQNhiBgMDJgZCA0BYiIDc4MGZj**** Date: Thu, 17 Mar 2026 11:18:32 GMT Content-Length: 0 Server: AliyunOSS
Exemplo 2: Estender a data limite de retenção
O exemplo a seguir estende a data limite de retenção de um objeto para 11 de março de 2027. No modo de conformidade, a data limite de retenção só pode ser estendida, nunca reduzida.
-
Solicitação de exemplo
PUT /exampleobject?retention&versionId=CAEQNhiBgMDJgZCA0BYiIDc4MGZj**** HTTP/1.1 Date: Thu, 17 Mar 2026 11:18:32 GMT Content-MD5: D3N3Z9CtiVqhCnZ9RjE**** Content-Type: application/xml Content-Length: 162 Host: examplebucket.oss-cn-hangzhou.aliyuncs.com Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20260317/cn-hangzhou/oss/aliyun_v4_request,Signature=**** <Retention> <Mode>COMPLIANCE</Mode> <RetainUntilDate>2027-03-11T00:00:00.000Z</RetainUntilDate> </Retention> -
Resposta de exemplo
HTTP/1.1 200 OK x-oss-request-id: 6485B3990232A65C3400**** x-oss-version-id: CAEQNhiBgMDJgZCA0BYiIDc4MGZj**** Date: Thu, 17 Mar 2026 11:20:15 GMT Content-Length: 0 Server: AliyunOSS
Códigos de erro
|
Código de erro |
Código de status HTTP |
Descrição |
|
InvalidRequest |
400 |
O ObjectWorm não está ativado para o bucket. Não é possível definir uma política de retenção de objeto. |
|
AccessDenied |
403 |
Não é possível reduzir a data limite de retenção no modo de conformidade. |