什麼是抄寫？

複製會將新建立的物件和物件更新從原始資料桶複製到目標資料桶。

• 只有新物件或現有物件的新版本（在複製規則新增到儲存桶後建立）才會複製到目標儲存桶。 現有的物件可以複 製到自己身上，建立複製的新版本。
• 來源物件的元資料會套用到複製的物件。
• 兩個儲存桶之間的雙向複製要求規則在兩個儲存桶上都處於活動狀態。
• 篩選器 (由前綴和/或標籤組成) 可用於設定複製規則的範圍，使其僅適用於某個物件子集。 單一原則中可定義多個規則，這些規則可指定不同的目的地。 以這種方式，同一個儲存桶中的不同物件可以複製到不同的目的地。

為何使用複製？

• 在不同地理位置的資料桶中保留一份資料副本。
• 透過定義複製規則，僅在允許的位置儲存複製品，以符合資料主權的合規規定。
• 保持生產與測試資料同步，因為複製會保留物件的元資料，例如最後修改時間、版本 ID 等。
• 透過為目標儲存桶定義不同的儲存類別和/或生命週期規則，為複製物件管理獨立於來源的儲存類別和生命週期政策。 同樣地，您也可以將儲存桶中的複製品儲存在單獨的服務實體甚至 IBM Cloud 帳戶中，同時也可以獨立控制對複製品的存取。

開始使用複製

要開始使用，以下是一些必須符合的先決條件：

• 在來源資料桶上設定 Writer 或 Manager 平台角色，或指定具有適當複製動作的自訂角色 (例如 cloud-object-storage.bucket.put_replication)。
• 您不需要擁有目標資料桶的存取權，但需要有足夠的平台角色來建立 新的 IAM 政策，允許源資料桶寫入目標資料桶。
• 目標磁碟桶不得啟用傳統磁碟桶防火牆，但可以使用 基於上下文的限制。
• 使用 SSE-C 加密的物件無法被複製，雖然 管理加密(SSE-KMS)如 Key Protect 與複製完全相容。
• 存檔狀態中的物件無法複製。
• 如果來源和目標儲存庫在不同的 IBM 帳戶中，請務必在每個帳戶中建立儲存庫。
• 在來源和目標儲存桶上啟用 版本控制。

由於版本化是複製的必要條件，因此不可能在以 不可變 Object Storage 政策 設定的儲存桶中複製物件。

使用一個 IBM 帳戶

若要在同一 IBM 帳戶的儲存桶之間複製物件，請執行下列步驟：

1. 導覽到您選擇的來源儲存桶後，按一下組態索引標籤。
2. 尋找 Bucket 複製，然後按一下設定複製按鈕。
3. 選擇 Replication source（複製來源 ），然後按一下 Next（下一步 ）。
4. 從下拉式功能表中選擇實體和儲存桶。 或者，將選項按鈕切換為否並貼入目標水桶的 CRN。
5. 按一下檢查權限按鈕。

現在，您需要在目標資料桶上授予來源資料桶 Writer 權限。 有幾種方法可以做到這一點，但最簡單的是使用 IBM Cloud Shell 和 IBM Cloud CLI。

1. 在新視窗或選項卡中開啟 IBM Cloud Shell。
2. 複製顯示在物件儲存主控台中的 IBM Cloud CLI 指令，並貼到新的 shell 中。
3. 回到水桶設定視窗或索引標籤，再次按一下檢查權限按鈕。

現在您要建立複製規則。

1. 確保規則狀態選項按鈕設為已啟用。
2. 指定規則的名稱和優先順序，以及任何前綴或標籤篩選條件，以限制受複製規則限制的物件。
3. 按一下完成。

使用不同的 IBM 帳戶

若要在不同 IBM 帳戶的儲存桶之間複製物件，請執行下列步驟：

1. 在目的地 IBM 帳戶上設定 IAM 政策。 有關建立 IAM 政策的資訊，請參閱 什麼是 IAM 政策以及誰可以指派這些 政策。
2. 在 Bucket Configuration 頁面上找到 CRN 格式的帳戶 ID 和服務實例 ID。
3. 使用目的地帳戶的 IBM Cloud UI，按一下 Manage>Access**(IAM)**。
4. 按一下左側面板中的驗證。
5. 按一下「建立」以建立新的 IAM 政策。
6. 授予服務授權頁面設定。 這是建立新 IAM 政策後的頁面。
7. 選擇另一個帳戶，並提供來源帳戶的帳戶 ID。
8. 提供服務存取 Cloud Object Storage.
9. 在存取範圍中，選擇特定資源。
10. 選擇來源服務實體，然後輸入源儲存桶的服務實體 ID。
11. 在「目標」下，選擇 Cloud Object Storage 來存取來源儲存桶。
12. 對於目標範圍，請選擇**特定資源>*服務實體。
13. 從下拉式功能表中選擇目的地帳戶的服務實例 ID。
14. 根據需要選擇角色 Object Writer 或 Writer。

物件寫入員角色足以啟用複製。

術語

來源儲存桶：已設定複製政策的儲存桶。 它是複製物件的來源。

目標儲存桶：在來源儲存桶複製政策中定義為目的地的儲存桶。 它是複製物件的目標。 也稱為「目的地」水桶。

複製：因向來源儲存桶提出請求而在目標儲存桶中建立的新物件。

複製什麼？

透過 CopyObject、PutObject 或 CompleteMultipartUpload 建立的新物件，會從來源儲存桶複製到目標儲存桶。 複製物件將從來源物件繼承下列元資料欄位：Etag, Last Modified Time, Version ID, user-attributes，和 Tags。

如果由複製政策設定，刪除標記將會被複製。

版本標籤的更新將從源資料桶複製到目標資料桶。

下列內容不會複製：

• 由生命週期事件啟動的行動
• 直接寫入存檔的物件
• 從存檔層級還原的物件
• 透過 SSE-C 加密的物件
• 物件 ACL

將複製用於業務連續性和災難恢復

複製可用於在服務中斷時提供服務的連續性：

• 確保源儲存桶和目標儲存桶位於不同位置。
• 驗證兩個儲存桶之間的物件最新版本是否同步。 工具，例如 Rclone ( rclone check 指令) 可以用來從指令行檢查同步性。
• 如果發生中斷，應用程式的流量可以重定向到目標資料桶。

一致性和資料完整性

雖然 IBM Cloud Object Storage 為所有資料 IO 作業提供了強大的一致性，但水桶組態最終會保持一致。 首次在儲存桶上啟用複製規則後，可能需要花一些時間才能讓設定傳遍整個系統，並開始複製新物件。

錯誤處理

複製失敗可能由多種原因引起，包括（但不限於）儲存桶設定錯誤、服務中斷、使用者與目標儲存桶的互動等。

COS 具備內建的容錯能力，可處理複製失敗的情況。 當發生失敗時，COS 可在長達 30 天內進行重試。 重試的頻率會因故障的性質而異。 舉例來說，由罕見的 I/O 錯誤所導致的失敗，可能會在數小時內重新嘗試；而因使用者儲存桶設定錯誤所導致的失敗，則可能每天重新嘗試一次。 若故障未能在 30 天內解決，系統將不再自動重新嘗試處理。 所有長期故障皆可透過 ListBucketReplicationFailures。

若您希望重新嘗試已超過 30 天的「過期」失敗案例，可透過 PutBucketReplicationFailureReattempt。

IAM 行動

有與複製相關的新 IAM 動作。

Activity Tracker 事件

抄寫會產生其他事件。

對於 cloud-object-storage.bucket-replication.create 事件，下列欄位提供額外資訊:

當抄寫作用中時，物件上的作業可能會產生下列額外資訊:

您可以從物件寫入來源時開始追蹤物件，直到在目標上寫入為止。 搜尋與物件寫入相關聯的要求 ID，應該會出現三個事件:

• 原始 PUT。
• 來自來源的同步要求。
• 目標上的 PUT 要求。

這三個遺漏中的任何一個都表示失敗。

使用情形和會計

所有抄本都是物件本身，且 提供使用情形 就像任何其他資料一樣。 順利完成抄寫會導致可計費 PUT、GET 及 HEAD 要求，雖然抄寫處理程序中所耗用的任何頻寬不會計費。

複製會產生額外的度量指標，供 IBM Cloud Monitoring 使用：

• ibm_cos_bucket_replication_sync_requests_issued
• ibm_cos_bucket_replication_sync_requests_received

互動

抄寫現有物件

抄寫規則只能在將規則配置並套用至儲存區 之後 寫入的物件上運作。 如果儲存區中有應該抄寫的現有物件，則需要讓抄寫處理程序知道物件的存在。 透過使用 PUT copy 作業將物件複製到物件本身，可以輕鬆達成此目的。

此處理程序將重設部分物件 meta 資料，包括建立時間戳記。 這將影響生命週期原則以及使用建立或修改時間戳記 (例如內容遞送網路) 的任何其他服務。 確保適當地處理重設物件 meta 資料可能導致的任何中斷。

該程序涉及:

1. 建立應該遵循抄寫規則之儲存區中所有物件的清單，
2. 反覆運算該清單，在來源與要求目標相同的每一個物件上執行 PUT copy 作業。

此範例只會抄寫 PUT copy 要求所建立物件的新版本。 為了抄寫物件的所有版本，也需要複製每一個個別版本。

下列範例以 Python撰寫，但演算法可以在任何程式設計語言或環境定義中套用。

import os
import sys
import ibm_boto3
from ibm_botocore.config import Config

# Create client connection
cos = ibm_boto3.client("s3",
                       ibm_api_key_id=os.environ.get('IBMCLOUD_API_KEY'),
                       ibm_service_instance_id=os.environ['SERVICE_INSTANCE_ID'],
                       config=Config(signature_version="oauth"),
                       endpoint_url=os.environ['US_GEO']
                       )

# Define the bucket with existing objects for replication
bucket = os.environ['BUCKET']

def copy_in_place(BUCKET_NAME):
    print("Priming existing objects in " + bucket + " for replication...")

    paginator = cos.get_paginator('list_objects_v2')
    pages = paginator.paginate(Bucket=bucket)

    for page in pages:
        for obj in page['Contents']:
            key = obj['Key']
            print("  * Copying " + key + " in place...")
            try:
                headers = cos.head_object(
                    Bucket=bucket,
                    Key=key
                    )
                md = headers["Metadata"]
                cos.copy_object(
                    CopySource={
                        'Bucket': bucket,
                        'Key': key
                        },
                    Bucket=bucket,
                    Key=key,
                    TaggingDirective='COPY',
                    MetadataDirective='REPLACE',
                    Metadata=md
                    )
                print("    Success!")
            except Exception as e:
                print("    Unable to copy object: {0}".format(e))
    print("Existing objects in " + bucket + " are now subject to replication rules.")

copy_in_place(bucket)

REST API 範例

下列範例使用 cURL 顯示以方便使用。 環境變數用來代表使用者特定的元素，例如 $BUCKET、$TOKEN 及 $REGION。 請注意，$REGION 也會包含任何網路類型規格，因此使用專用網路將要求傳送至 us-south 中的儲存區需要將變數設為 private.us-south。

curl -X "PUT" "https://$BUCKET.s3.$REGION.cloud-object-storage.appdomain.cloud/?replication" \
     -H 'Authorization: bearer $TOKEN' \
     -H 'Content-MD5: exuBoz2kFBykNwqu64JZuA==' \
     -H 'Content-Type: text/plain; charset=utf-8' \
     -d $'<ReplicationConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
            <Rule>
              <ID>SimpleReplication</ID>
              <Priority>1</Priority>
              <Status>Enabled</Status>
              <DeleteMarkerReplication>
                <Status>Disabled</Status>
              </DeleteMarkerReplication>
              <Filter/>
              <Destination>
                <Bucket>$DESTINATION_CRN</Bucket>
              </Destination>
          	</Rule>
          </ReplicationConfiguration>'

curl -X "PUT" "https://$BUCKET.s3.$REGION.cloud-object-storage.appdomain.cloud/?replication" \
     -H 'Authorization: bearer $TOKEN' \
     -H 'Content-MD5: exuBoz2kFBykNwqu64JZuA==' \
     -H 'Content-Type: text/plain; charset=utf-8' \
     -d $'<ReplicationConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
            <Rule>
              <ID>ProjectA</ID>
              <Priority>10</Priority>
              <Status>Enabled</Status>
              <DeleteMarkerReplication>
                <Status>Enabled</Status>
              </DeleteMarkerReplication>
              <Filter>
                <Prefix>project_a/</prefix>
              </Filter>
              <Destination>
                <Bucket>$DESTINATION_CRN_A</Bucket>
              </Destination>
          	</Rule>
            <Rule>
              <ID>ProjectB</ID>
              <Priority>5</Priority>
              <Status>Enabled</Status>
              <DeleteMarkerReplication>
                <Status>Enabled</Status>
              </DeleteMarkerReplication>
              <Filter>
                <Prefix>project_b/</prefix>
              </Filter>
              <Destination>
                <Bucket>$DESTINATION_CRN_B</Bucket>
              </Destination>
          	</Rule>
            <Rule>
              <ID>AcmeCorp</ID>
              <Priority>20</Priority>
              <Status>Enabled</Status>
              <DeleteMarkerReplication>
                <Status>Enabled</Status>
              </DeleteMarkerReplication>
              <Filter>
                <Tag>
                  <Key>Client</Key>
                  <Value>ACME</Value>
                </Tag>
              </Filter>
              <Destination>
                <Bucket>$DESTINATION_CRN_C</Bucket>
              </Destination>
          	</Rule>
          </ReplicationConfiguration>'

curl -X "GET" "https://$BUCKET.s3.$REGION.cloud-object-storage.appdomain.cloud/?replication" \
     -H 'Authorization: bearer $TOKEN'

<ReplicationConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Rule>
    <ID>SimpleReplication</ID>
    <Status>ENABLED</Status>
    <DeleteMarkerReplication>
      <Status>DISABLED</Status>
    </DeleteMarkerReplication>
    <Destination>
      <Bucket>crn:v1:bluemix:public:cloud-object-storage:global:a/9978e07eXXXXXXXX66c89c428028654:ef1c725e-XXXX-4967-bcc1-734c03a2b846:bucket:replication-destination</Bucket>
    </Destination>
    <Priority>1</Priority>
    <Filter/>
  </Rule>
</ReplicationConfiguration>

curl -X "DELETE" "https://$BUCKET.s3.$REGION.cloud-object-storage.appdomain.cloud/?replication" \
     -H 'Authorization: bearer $TOKEN'

curl -X "GET" "https://$BUCKET.s3.$REGION.cloud-object-storage.appdomain.cloud/?ibm-replication-failures" \
     -H 'Authorization: bearer $TOKEN'

<ListReplicationFailureResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <Name>example</Name>
    <FirstSyncAttemptedBefore>2025-12-15T00:00:00.000Z</FirstSyncAttemptedBefore>
    <MaxKeys>10</MaxKeys>
    <IsTruncated>false</IsTruncated>
    <EncodingType>false</EncodingType>
    <KeyCount>2</KeyCount>
    <Contents>
        <Key>test-obj+*1765434016787</Key>
        <VersionId>00000000-0000-0000-0000-019b0c114413</VersionId>
        <SyncType>Content</SyncType>
        <FirstSyncAttempted>2025-12-11T06:20:16.787Z</FirstSyncAttempted>
        <LastSyncAttempted>2025-12-11T06:20:16.787Z</LastSyncAttempted>
        <SyncFailureCause>Versioning disabled on destination bucket</SyncFailureCause>
    </Contents>
    <Contents>
        <Key>test-obj+*1765434016786</Key>
        <VersionId>00000000-0000-0000-0000-019b0c114412</VersionId>
        <SyncType>Content</SyncType>
        <FirstSyncAttempted>2025-12-11T06:20:16.786Z</FirstSyncAttempted>
        <LastSyncAttempted>2025-12-11T06:20:16.786Z</LastSyncAttempted>
        <SyncFailureCause>Replication operation not authorized on target bucket</SyncFailureCause>
    </Contents>
</ListReplicationFailureResult>

curl -X "PUT" "https://$BUCKET.s3.$REGION.cloud-object-storage.appdomain.cloud/?ibm-replication-reattempt" \
     -H 'Authorization: bearer $TOKEN'

HTTP/1.1 204 No Content
Connection: close
...
x-ibm-replication-reattempt-scheduled-time: Fri, 12 Dec 2025 00:00:00 GMT

SDK 範例

下列範例使用 IBM COS SDK for Python 及 Node.js，雖然物件版本化的實作應該與任何容許設定自訂端點的 S3-compatible 程式庫或工具完全相容。 使用協力廠商工具需要 HMAC 認證來計算 AWS V4 簽章。 如需 HMAC 認證的相關資訊，請參閱文件。

#!/usr/bin/env python3

import ibm_boto3
from ibm_botocore.config import Config
from ibm_botocore.exceptions import ClientError

# Define constants
API_KEY = os.environ.get('IBMCLOUD_API_KEY')
SERVICE_INSTANCE = os.environ.get('SERVICE_INSTANCE_ID')
ENDPOINT = os.environ.get('ENDPOINT')

BUCKET = "my-replication-bucket" # The bucket that will enable replication.

# Create resource client with configuration info pulled from environment variables.
cosClient = ibm_boto3.client("s3",
                         ibm_api_key_id=API_KEY,
                         ibm_service_instance_id=SERVICE_INSTANCE,
                         config=Config(signature_version="oauth"),
                         endpoint_url=ENDPOINT
                         )

response = cosClient.put_bucket_versioning(
    Bucket=BUCKET,
    ReplicationConfiguration={
        'Rules': [
            {
                'ID': 'string',
                'Priority': 123,
                'Filter': {
                    'Prefix': 'string',
                    'Tag': {
                        'Key': 'string',
                        'Value': 'string'
                    },
                    'And': {
                        'Prefix': 'string',
                        'Tags': [
                            {
                                'Key': 'string',
                                'Value': 'string'
                            },
                        ]
                    }
                },
                'Status': 'Enabled'|'Disabled',
                'Destination': {
                    'Bucket': 'string',
                },
                'DeleteMarkerReplication': {
                    'Status': 'Enabled'|'Disabled'
                }
            },
        ]
    }
)

resp = cosClient.list_object_versions(Prefix='some-prefix', Bucket=BUCKET)

const IBM = require('ibm-cos-sdk');

var config = {
    endpoint: '<endpoint>',
    apiKeyId: '<api-key>',
    serviceInstanceId: '<resource-instance-id>',
};

var cos = new IBM.S3(config);

var params = {
  Bucket: 'STRING_VALUE', /* required */
  ReplicationConfiguration: { /* required */
    Role: 'STRING_VALUE', /* required */
    Rules: [ /* required */
      {
        Destination: { /* required */
          Bucket: 'STRING_VALUE', /* required */
        },
        Status: Enabled | Disabled, /* required */
        Filter: {
          And: {
            Prefix: 'STRING_VALUE',
            Tags: [
              {
                Key: 'STRING_VALUE', /* required */
                Value: 'STRING_VALUE' /* required */
              },
              /* more items */
            ]
          },
          Prefix: 'STRING_VALUE',
          Tag: {
            Key: 'STRING_VALUE', /* required */
            Value: 'STRING_VALUE' /* required */
          }
        },
        ID: 'STRING_VALUE',
        Prefix: 'STRING_VALUE',
        Priority: 'NUMBER_VALUE',
        }
      }
    ]
  },
  ContentMD5: 'STRING_VALUE',
};
cos.putBucketReplication(params, function(err, data) {
  if (err) console.log(err, err.stack); // an error occurred
  else     console.log(data);           // successful response
});