复制对象

什么是复制？

复制功能可将新创建的对象和对象更新从源数据桶复制到目标数据桶。

• 只有新对象或现有对象的新版本（在复制规则添加到存储桶后创建）才会复制到目标存储桶。 现有对象可以 通过复制到自身来 复制，从而创建一个新的复制版本。
• 源对象的元数据会应用到复制的对象中。
• 两个存储桶之间的双向复制要求两个存储桶上的规则都处于活动状态。
• 过滤器（由前缀和/或标记组成）可用于限定复制规则的范围，使其仅适用于部分对象。 单个策略中可定义多个规则，这些规则可指定不同的目的地。 通过这种方式，同一数据桶中的不同对象可以复制到不同的目的地。

为什么要使用复制？

• 在不同地理位置的数据桶中保存一份数据副本。
• 通过定义复制规则，仅在允许的位置存储副本，满足数据主权的合规性规定。
• 保持生产数据和测试数据同步，因为复制会保留对象元数据，如最后修改时间、版本 ID 等。
• 通过为目标存储桶定义不同的存储类别和/或生命周期规则，为复制对象管理独立于源的存储类别和生命周期策略。 同样，你也可以在单独的服务实例甚至 IBM Cloud 账户中将副本存储在一个桶中，并独立控制对副本的访问。

开始复制

要开始工作，必须满足以下一些先决条件：

• 在源数据桶上设置 Writer 或 Manager 平台角色，或指定具有相应复制操作（如 cloud-object-storage.bucket.put_replication ）的自定义角色。
• 您不需要有访问目标存储桶的权限，但需要有足够的平台角色来创建允许源存储桶写入目标存储桶的 新 IAM 策略。
• 目标桶必须未启用传统桶防火墙，但可以使用 基于上下文的限制。
• 使用 SSE-C 加密的对象不能复制，但 Key Protect 等托管加密（SSE-KMS） 与复制完全兼容。
• 无法复制处于存档状态的对象。
• 如果源存储桶和目标存储桶在不同的 IBM 账户中，请确保在每个账户中创建存储桶。
• 在源存储桶和目标存储桶上启用 版本控制。

由于版本管理是复制的必要条件，因此不可能在使用 不可变 Object Storage 策略 配置的存储桶中复制对象。

使用一个 IBM 账户

要在同一 IBM 账户中的存储桶之间复制对象，请执行以下操作：

1. 导航到所选源桶后，单击“配置”选项卡。
2. 查找“Bucket 复制”，然后单击“设置复制”按钮。
3. 选择复制源，然后单击 “下一步”。
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 配置”页面上找到 CRN 格式的账户 ID 和服务实例 ID。
3. 使用目标账户的 IBM Cloud UI，单击“管理”>“访问**（IAM）**”。
4. 单击左侧面板中的身份验证。
5. 单击 “创建”以创建新的 IAM 策略。
6. 授予服务授权页面配置。 这是创建新 IAM 策略后的页面。
7. 选择另一个账户，并提供源账户的账户 ID。
8. 提供以下服务 Cloud Object Storage.
9. 在访问范围中，选择特定资源。
10. 选择源服务实例，然后输入源桶的服务实例 ID。
11. 在目标下，选择 Cloud Object Storage 作为源桶访问。
12. 对于目标范围，选择**特定资源>*服务实例。
13. 从下拉菜单中选择目标账户的服务实例 ID。
14. 根据需要选择“对象写入器”或 “写入器”角色。

对象写入器角色足以启用复制。

术语

源数据桶：为其配置复制策略的桶。 它是复制对象的来源。

目标存储桶：在源数据桶复制策略中被定义为目标的数据桶。 它是复制对象的目标。 也称为“目的地”水桶。

复制：因向源桶发出请求而在目标桶中创建的新对象。

复制了什么？

通过 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 事件，以下字段提供额外的信息:

当复制处于活动状态时，对对象执行的操作可能会生成以下额外信息:

您可以从将对象写入源时开始跟踪该对象，直到在目标上写入该对象为止。 搜索与对象写相关联的请求标识，应显示三个事件:

• 原始 PUT。
• 来自源的同步请求。
• 目标上的 PUT 请求。

这三个缺失值中的任何一个表示发生故障。

使用情况和会计

所有副本都是对象本身，并且 添加用法 与任何其他数据一样。 成功复制会导致计费 PUT，GET 和 HEAD 请求，但不会对复制过程中使用的任何带宽进行计费。

复制会生成更多指标，供 IBM Cloud Monitoring 使用：

• ibm_cos_bucket_replication_sync_requests_issued
• ibm_cos_bucket_replication_sync_requests_received

交互

复制现有对象

复制规则只能对 在 配置规则并将其应用于存储区之后写入的对象执行操作。 如果存储区中存在应复制的现有对象，那么需要使复制过程了解这些对象是否存在。 通过使用 PUT copy 操作将对象复制到自身，可以轻松完成此操作。

此过程将重置一些对象元数据，包括创建时间戳记。 这将影响生命周期策略以及使用创建或修改时间戳记 (例如内容交付网络) 的任何其他服务。 确保适当处理重置对象元数据可能引起的任何中断。

这一进程涉及:

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
});