全部產品
Search

搜尋本產品

    Object Storage Service：PutObjectRetention

    文件中心

    Object Storage Service：PutObjectRetention

    更新時間：Apr 01, 2026

    調用PutObjectRetention介面為指定Object版本設定保留原則，包括保留模式和保留到期日。對象層級的保留原則優先順序高於Bucket維度設定的ObjectWorm預設保留原則。

    注意事項

    重要

    該功能目前為邀測功能，如需使用，請聯絡支援人員申請開通。當前僅支援華東1（杭州）、西南1（成都）、華南1（深圳）、華南3（廣州）、華北1（青島）、華北2（北京）、華北5（呼和浩特）、華南2（河源）、中國香港、德國（法蘭克福）、日本（東京）、韓國（首爾）、新加坡、馬來西亞（吉隆坡）、印尼（雅加達）、菲律賓（馬尼拉）、泰國（曼穀）、沙特（利雅得）、阿聯酋（杜拜）地區。

    • 調用該介面前，Bucket必須已通過PutBucketObjectWormConfiguration介面開啟對象層級保留原則（ObjectWorm）。

    • 調用該介面需要具備oss:PutObjectRetention許可權。

    • 在合規模式（COMPLIANCE）下，保留到期日（RetainUntilDate）只能延長，不能縮短。如果設定的日期早於當前保留到期日，將返回錯誤。

    • Object層級的保留原則優先順序高於Bucket維度設定的ObjectWorm預設保留原則。如果Object已通過此介面設定了獨立的保留原則，則以Object層級的策略為準。

    • 對Append類型的檔案暫不支援設定保留原則。

    • 保留到期日（RetainUntilDate）必須晚於目前時間。

    請求文法

    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: SignatureValue

    請求參數

    參數名稱

    類型

    是否必選

    樣本值

    描述

    retention

    不涉及

    是

    不涉及

    固定請求參數，用於指定本次操作為設定對象保留原則。

    versionId

    字串

    否

    CAEQNhiBgMDJgZCA0BYiIDc4MGZj****

    Object的版本ID。如果不指定，則預設對最新版本的Object進行操作。

    要求標頭

    參數名稱

    類型

    是否必選

    樣本值

    描述

    Content-MD5

    字串

    是

    B2M2Y8AsgTpgAmY7PhC****

    請求體的MD5雜湊值，用於資料完整性校正。

    x-oss-bypass-governance-retention

    布爾類型

    否

    true

    在需要繞過治理模式保留原則時設定為true。需要具備oss:BypassGovernanceRetention許可權。僅對治理模式（GOVERNANCE）有效，對合規模式（COMPLIANCE）無效。

    請求元素

    名稱

    類型

    是否必須

    樣本值

    描述

    Retention

    容器

    是

    不涉及

    配置Object保留原則的容器。

    父節點：無

    子節點：Mode、RetainUntilDate

    Mode

    字串

    是

    COMPLIANCE

    Object的保留模式。取值：

    • COMPLIANCE（合規模式）：保留期內，任何使用者（包括根使用者）都無法刪除或覆蓋寫受保護的對象版本，保留期限也不可縮短。

    父節點：Retention

    RetainUntilDate

    字串

    是

    2026-10-11T00:00:00.000Z

    Object的保留到期日，ISO 8601格式。在此日期之前，該Object版本不允許被刪除或覆蓋寫。該時間必須晚於目前時間。

    在合規模式下，該日期只能延長不能縮短。

    父節點：Retention

    回應標頭

    名稱

    樣本值

    描述

    x-oss-version-id

    CAEQNhiBgMDJgZCA0BYiIDc4MGZj****

    被設定保留原則的Object版本ID。

    樣本

    樣本1：為Object設定合規模式保留原則

    • 請求樣本

      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>

    • 返回樣本

      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

    樣本2：延長保留到期日

    以下樣本將Object的保留到期日從原有日期延長到2027年3月11日。在合規模式下，保留到期日只能延長不能縮短。

    • 請求樣本

      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>

    • 返回樣本

      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

    錯誤碼

    錯誤碼

    HTTP狀態代碼

    描述

    InvalidRequest

    400

    Bucket未開啟ObjectWorm，無法設定Object保留原則。

    AccessDenied

    403

    在合規模式下嘗試縮短保留到期日。合規模式下保留到期日只能延長不能縮短。