Object Storage Service：保留原則（WORM）

前提條件

確保需要設定保留原則的Bucket未開啟版本控制。關於版本控制的更多資訊，請參見版本控制介紹。

使用情境

OSS保留原則支援的WORM特性符合美國證券交易委員會（SEC）和金融業監管局（FINRA）的合規要求。適用於金融、保險、醫學、證券、日誌資料等保審查等情境。

注意事項

• 目前僅支援針對Bucket層級設定保留原則。

• 同一個Bucket中，不建議同時開通OSS-HDFS服務並設定保留原則。

  如果Bucket開通了OSS-HDFS服務並設定了保留原則，會導致通過OSS-HDFS提供的方式刪除.dlsdata/目錄下的資料時提示刪除成功，但在保留原則有效期間內OSS仍將保留該目錄下被刪除的資料，且在保留原則失效後也無法識別並刪除.dlsdata/目錄下相關的資料。

• Bucket內的Object在保留原則生效期間，可通過設定生命週期規則進行儲存類型轉化，在保證合規性的前提下，降低儲存成本。

規則說明

• 生效規則

  當基於時間的保留原則建立後，該策略預設處於InProgress狀態，有效期間為24小時。在此期間，Bucket資源處於保護狀態。

  • 啟動保留原則24小時內

    • 如果24小時內未提交鎖定保留原則，則Bucket所有者以及授權使用者可以刪除該策略。

    • 如果24小時內已提交鎖定保留原則，則不允許刪除該策略，且無法縮短保護周期，僅可延長保護周期。同時，Bucket內的資料處於保護狀態，嘗試刪除或修改這些資料時，OSS將返回409 FileImmutable錯誤資訊。

  • 啟動保留原則24小時後

    如果超過24小時未鎖定該保留原則，則該策略自動失效，您可以刪除該策略。

• 刪除規則

  • 基於時間的保留原則是Bucket的一種Metadata屬性。當刪除某個Bucket時，該Bucket對應的保留原則也會被刪除。

  • 啟動保留原則24小時內，如果該保留原則未提交鎖定，則Bucket所有者以及授權使用者可以刪除該策略。

  • 如果Bucket內有Object處於保護周期內，那麼您將無法刪除保留原則，同時也無法刪除Bucket。

• 規則樣本

  假設您在2022年06月01日為某個Bucket建立了保護周期為30天的保留原則，且該策略在建立後進入鎖定狀態。您在不同時間上傳了file1.txt、file2.txt、file3.txt三個Object。具體上傳時間及到期時間如下：

  Object名稱	上傳時間	Object到期時間
  file1.txt	2022年04月01日	2022年04月30日
  file2.txt	2022年06月01日	2022年06月30日
  file3.txt	2022年09月01日	2022年09月30日

操作方式

import com.aliyun.oss.ClientException;
import com.aliyun.oss.OSS;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.OSSClientBuilder;
import com.aliyun.oss.OSSException;
import com.aliyun.oss.model.InitiateBucketWormRequest;
import com.aliyun.oss.model.InitiateBucketWormResult;

public class Demo {

    public static void main(String[] args) throws Exception {
        // Endpoint以華東1（杭州）為例，其它Region請按實際情況填寫。
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // 從環境變數中擷取訪問憑證。運行本程式碼範例之前，請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // 填寫Bucket名稱，例如examplebucket。
        String bucketName = "examplebucket";
        // 填寫Bucket所在地區。以華東1（杭州）為例，Region填寫為cn-hangzhou。
        String region = "cn-hangzhou";

        // 建立OSSClient執行個體。
        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);        
        OSS ossClient = OSSClientBuilder.create()
        .endpoint(endpoint)
        .credentialsProvider(credentialsProvider)
        .clientConfiguration(clientBuilderConfiguration)
        .region(region)               
        .build();

        try {
            // 建立InitiateBucketWormRequest對象。
            InitiateBucketWormRequest initiateBucketWormRequest = new InitiateBucketWormRequest(bucketName);
            // 指定Object保護天數為1天。
            initiateBucketWormRequest.setRetentionPeriodInDays(1);

            // 建立合規保留原則。
            InitiateBucketWormResult initiateBucketWormResult = ossClient.initiateBucketWorm(initiateBucketWormRequest);

            // 查看合規保留原則ID。
            String wormId = initiateBucketWormResult.getWormId();
            System.out.println(wormId);
        } catch (OSSException oe) {
            System.out.println("Caught an OSSException, which means your request made it to OSS, "
                    + "but was rejected with an error response for some reason.");
            System.out.println("Error Message:" + oe.getErrorMessage());
            System.out.println("Error Code:" + oe.getErrorCode());
            System.out.println("Request ID:" + oe.getRequestId());
            System.out.println("Host ID:" + oe.getHostId());
        } catch (ClientException ce) {
            System.out.println("Caught an ClientException, which means the client encountered "
                    + "a serious internal problem while trying to communicate with OSS, "
                    + "such as not being able to access the network.");
            System.out.println("Error Message:" + ce.getMessage());
        } finally {
            if (ossClient != null) {
                ossClient.shutdown();
            }
        }
    }
}

<?php
if (is_file(__DIR__ . '/../autoload.php')) {
    require_once __DIR__ . '/../autoload.php';
}
if (is_file(__DIR__ . '/../vendor/autoload.php')) {
    require_once __DIR__ . '/../vendor/autoload.php';
}

use OSS\Credentials\EnvironmentVariableCredentialsProvider;
use OSS\OssClient;
use OSS\CoreOssException;

// 從環境變數中擷取訪問憑證。運行本程式碼範例之前，請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。 
$provider = new EnvironmentVariableCredentialsProvider();
// Endpoint以杭州為例，其它Region請按實際情況填寫。
$endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
$bucket= "<yourBucketName>";

$config = array(
        "provider" => $provider,
        "endpoint" => $endpoint,
        "signatureVersion" => OssClient::OSS_SIGNATURE_VERSION_V4,
        "region"=> "cn-hangzhou"
    );
    $ossClient = new OssClient($config);

try {
    // 建立保留原則，指定Object保護天數為30天。
    $wormId = $ossClient->initiateBucketWorm($bucket, 30);

    // 查看保留原則ID。
    print($wormId);
} catch (OssException $e) {
    printf(__FUNCTION__ . ": FAILED\n");
    printf($e->getMessage() . "\n");
    return;
}

print(__FUNCTION__ . ": OK" . "\n"); 

const OSS = require('ali-oss');

const client = new OSS({
  // yourregion填寫Bucket所在地區。以華東1（杭州）為例，Region填寫為oss-cn-hangzhou。
  region: 'yourregion',
  // 從環境變數中擷取訪問憑證。運行本程式碼範例之前，請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,  
  authorizationV4: true,
  // yourBucketName填寫Bucket名稱。
  bucket: 'yourBucketName',
});
// 建立保留原則。
async function initiateBucketWorm() {
 // yourbucketname填寫儲存空間名稱。
  const bucket = 'yourbucketname'
  // 指定Object保護天數。
  const days = '<Retention Days>'
    const res = await client.initiateBucketWorm(bucket, days)
  console.log(res.wormId)
}

initiateBucketWorm()

# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
# 從環境變數中擷取訪問憑證。運行本程式碼範例之前，請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# 填寫Bucket所在地區對應的Endpoint。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
# 填寫Endpoint對應的Region資訊，例如cn-hangzhou。注意，v4簽名下，必須填寫該參數
region = "cn-hangzhou"

# yourBucketName填寫儲存空間名稱。
bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)

# 建立保留原則，並指定Object保護天數為1天。
result = bucket.init_bucket_worm(1)
# 查看保留原則ID。
print(result.worm_id)

package main

import (
	"log"

	"github.com/aliyun/aliyun-oss-go-sdk/oss"
)

func main() {
	// 從環境變數中擷取訪問憑證。運行本程式碼範例之前，請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
	provider, err := oss.NewEnvironmentVariableCredentialsProvider()
	if err != nil {
		log.Fatalf("Error creating credentials provider: %v", err)
	}

	// 建立OSSClient執行個體。
	// yourEndpoint填寫Bucket對應的Endpoint，以華東1（杭州）為例，填寫為https://oss-cn-hangzhou.aliyuncs.com。其它Region請按實際情況填寫。
	// yourRegion填寫Bucket所在地區，以華東1（杭州）為例，填寫為cn-hangzhou。其它Region請按實際情況填寫。
	clientOptions := []oss.ClientOption{oss.SetCredentialsProvider(&provider)}
	clientOptions = append(clientOptions, oss.Region("yourRegion"))
	// 設定簽名版本
	clientOptions = append(clientOptions, oss.AuthVersion(oss.AuthV4))
	client, err := oss.New("yourEndpoint", "", "", clientOptions...)
	if err != nil {
		log.Fatalf("Error creating OSS client: %v", err)
	}

	// 填寫待配置合規保留原則的Bucket名稱。
	bucketName := "<yourBucketName>"

	// 指定Object保護天數為60天。
	result, err := client.InitiateBucketWorm(bucketName, 60)
	if err != nil {
		log.Fatalf("Error initiating bucket WORM: %v", err)
	}

	log.Println("WORM policy initiated successfully:", result)
}

#include <alibabacloud/oss/OssClient.h>
using namespace AlibabaCloud::OSS;

int main(void)
{
    /* 初始化OSS帳號資訊。*/
            
    /* yourEndpoint填寫Bucket所在地區對應的Endpoint。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。*/
    std::string Endpoint = "yourEndpoint";
    /* yourRegion填寫Bucket所在地區對應的Region。以華東1（杭州）為例，Region填寫為cn-hangzhou。*/
    std::string Region = "yourRegion";
    /* 填寫Bucket名稱，例如examplebucket。*/
    std::string BucketName = "examplebucket";

      /* 初始化網路等資源。*/
      InitializeSdk();

      ClientConfiguration conf;
      conf.signatureVersion = SignatureVersionType::V4;
      /* 從環境變數中擷取訪問憑證。運行本程式碼範例之前，請確保已設定環境變數OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。*/
    auto credentialsProvider = std::make_shared<EnvironmentVariableCredentialsProvider>();
    OssClient client(Endpoint, credentialsProvider, conf);
    client.SetRegion(Region);
  
      /* 建立保留原則，指定Object保護天數為1天。*/
      auto outcome = client.InitiateBucketWorm(InitiateBucketWormRequest(BucketName, 1));

      if (outcome.isSuccess()) {      
            std::cout << " InitiateBucketWorm success " << std::endl;
            std::cout << "WormId:" << outcome.result().WormId() << std::endl;
      }
      else {
        /* 異常處理。*/
        std::cout << "InitiateBucketWorm fail" <<
        ",code:" << outcome.error().Code() <<
        ",message:" << outcome.error().Message() <<
        ",requestId:" << outcome.error().RequestId() << std::endl;
        return -1;
      }

      /* 釋放網路等資源。*/
      ShutdownSdk();
      return 0;
}

ossutil api initiate-bucket-worm --bucket examplebucket --initiate-worm-configuration "{\"RetentionPeriodInDays\":\"365\"}"

相關API

以上操作方式底層基於API實現，如果您的程式自訂要求較高，您可以直接發起REST API請求。直接發起REST API請求需要手動編寫代碼計算簽名。更多資訊，請參見InitiateBucketWorm。

常見問題