Defina uma política de retenção para uma versão específica de um objeto, impedindo que a exclua ou modifique até uma data especificada. Esta operação é essencial para 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 no nível do bucket, permitindo um controle granular sobre objetos individuais.
Notas de uso
Atualmente, este 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) para o bucket chamando a operação
PutBucketObjectWormConfiguration. Se o ObjectWorm não estiver ativado, a solicitação falhará com o erroInvalidRequest.Para chamar esta operação, é necessário ter a permissão
oss:PutObjectRetention. Você pode conceder essa permissão por meio de políticas do RAM ou políticas de bucket.No modo de conformidade, você só pode estender o valor de
RetainUntilDate, nunca reduzi-lo. Não defina uma data anterior à data de retenção atual, pois retorna um erroAccessDenied. Isso garante a imutabilidade dos dados para os requisitos de conformidade.As políticas de retenção no nível do objeto definidas por esta operação substituem a política de retenção no nível do bucket. Isso permite aplicar requisitos de retenção mais rigorosos a objetos específicos, mantendo uma política padrão para o bucket.
Objetos anexáveis (appendable objects) não suportam políticas de retenção. Não defina uma política de retenção em um objeto anexável, pois a solicitação falhará.
O valor de
RetainUntilDatedeve ser uma data futura. O sistema rejeita datas passadas ou atuais.As políticas de retenção funcionam com o controle de versão. Caso não especifique um
versionId, 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 sua solicitação.Durante o período de retenção, o sistema impede que exclua, sobrescreva ou reduza a retenção das versões protegidas do objeto, 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 |
Especifique que a operação configura uma política de retenção de objeto. Este é um parâmetro de consulta obrigatório para indicar a operação de retenção. |
|
versionId |
String |
Não |
CAEQNhiBgMDJgZCA0BYiIDc4MGZj**** |
O ID da versão do objeto. Se você não especificar este parâmetro, 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 é usado para verificação da integridade dos dados. |
Elementos do corpo da solicitação
|
Elemento |
Tipo |
Obrigatório |
Exemplo |
Descrição |
|
Retention |
Container |
Sim |
N/A |
O contêiner para a 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 é uma data no formato ISO 8601. Antes dessa data, não exclua ou sobrescreva a versão do objeto. A data especificada deve ser no futuro. No modo de conformidade, essa data só pode ser estendida e não pode ser reduzida. Pai: Retention |
Cabeçalhos da resposta
|
Cabeçalho |
Exemplo |
Descrição |
|
x-oss-version-id |
CAEQNhiBgMDJgZCA0BYiIDc4MGZj**** |
O ID da versão do objeto ao qual a política de retenção se aplica. |
Exemplos
Exemplo 1: Definir uma política de retenção no modo de conformidade
-
Exemplo de solicitação
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> -
Exemplo de resposta
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 e não pode ser reduzida.
-
Exemplo de solicitação
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> -
Exemplo de resposta
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 defina uma política de retenção de objeto. |
|
AccessDenied |
403 |
Você não pode reduzir a data limite de retenção no modo de conformidade. |