如何使用PHP V2进行数据复制_对象存储(OSS)-阿里云帮助中心

数据复制是以异步（近实时）方式将源Bucket中的文件（Object）以及对Object的创建、更新和删除等操作自动复制到目标Bucket。OSS支持跨区域复制（Cross-Region Replication）和同区域复制（Same-Region Replication）。

注意事项

本文示例代码以华东1（杭州）的地域IDcn-hangzhou为例，默认使用外网Endpoint，如果您希望通过与OSS同地域的其他阿里云产品访问OSS，请使用内网Endpoint。关于OSS支持的Region与Endpoint的对应关系，请参见OSS地域和访问域名。
阿里云账号默认拥有数据复制的相关权限。如果您希望通过RAM用户或者STS的方式执行数据复制相关操作，例如：
- 开启数据复制，您必须拥有oss:PutBucketReplication权限。
- 开启或关闭数据复制时间控制（RTC）功能，您必须拥有oss:PutBucketRtc权限。
- 查看数据复制规则，您必须拥有oss:GetBucketReplication权限。
- 查看可复制的目标地域，您必须拥有oss:GetBucketReplicationLocation权限。
- 查看数据复制进度，您必须拥有oss:GetBucketReplicationProgress权限。
- 关闭数据复制，您必须拥有oss:DeleteBucketReplication权限

示例代码

开启数据复制

重要

开启数据复制前，请确保源存储空间与目标存储空间同时处于非版本化或已启用版本控制状态。

以下代码用于开启数据复制，将源Bucket中的数据复制到相同或不同地域下的目标Bucket。

<?php

// 引入 Composer 自动加载文件，确保 SDK 和其他依赖可以被正确加载
require_once __DIR__ . '/../vendor/autoload.php';

// 使用 Alibaba Cloud OSS V2 命名空间
use AlibabaCloud\Oss\V2 as Oss;

// 定义命令行参数说明和是否为必填项
$optsdesc = [
    "region" => ['help' => 'The region in which the bucket is located.', 'required' => True],
    "endpoint" => ['help' => 'The domain names that other services can use to access OSS.', 'required' => False],
    "bucket" => ['help' => 'The name of the bucket', 'required' => True],
    "target-bucket" => ['help' => 'The name of the target bucket', 'required' => True],
    "target-location" => ['help' => 'The location of the target bucket', 'required' => True],
];

// 构建 getopt 所需的长选项数组格式：如 ["region:", "endpoint:", ...]
$longopts = \array_map(function ($key) {
    return "$key:";
}, array_keys($optsdesc));

// 获取命令行传入的参数
$options = getopt("", $longopts);

// 检查所有必填参数是否都已提供，若缺失则输出错误信息并退出
foreach ($optsdesc as $key => $value) {
    if ($value['required'] === True && empty($options[$key])) {
        $help = $value['help'];
        echo "Error: the following arguments are required: --$key, $help";
        exit(1);
    }
}

// 提取命令行参数值
$region = $options["region"];
$bucket = $options["bucket"];
$targetBucket = $options["target-bucket"];
$targetLocation = $options["target-location"];

// 使用环境变量中的凭证信息（例如 OSS_ACCESS_KEY_ID 和 OSS_ACCESS_KEY_SECRET）
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

// 加载默认配置
$cfg = Oss\Config::loadDefault();

// 设置凭证提供者、区域和可选的 Endpoint
$cfg->setCredentialsProvider($credentialsProvider);
$cfg->setRegion($region);
if (isset($options["endpoint"])) {
    $cfg->setEndpoint($options["endpoint"]);
}

// 创建 OSS 客户端实例
$client = new Oss\Client($cfg);

// 构造 PutBucketReplication 请求对象
$request = new Oss\Models\PutBucketReplicationRequest(
    bucket: $bucket,
    replicationConfiguration: new Oss\Models\ReplicationConfiguration(
        rules: array(
            new Oss\Models\ReplicationRule(
                destination: new Oss\Models\ReplicationDestination(
                    bucket: $targetBucket,
                    location: $targetLocation,
                ),
                rtc: new Oss\Models\ReplicationTimeControl(
                    status: 'enabled' // 启用复制时间控制（RTC）
                )
            )
        )
    )
);

// 执行请求并获取结果
$result = $client->putBucketReplication($request);

// 输出响应的状态码、请求ID和复制规则ID
printf(
    'status code:' . $result->statusCode . PHP_EOL .
    'request id:' . $result->requestId . PHP_EOL .
    'replication rule id:' . $result->replicationRuleId
);

查看数据复制规则

以下代码用于查看Bucket的数据复制规则。

<?php

// 引入 Composer 的自动加载文件，确保 SDK 和依赖类可以被正确加载
require_once __DIR__ . '/../vendor/autoload.php';

// 使用 Alibaba Cloud OSS V2 命名空间并简写为 Oss
use AlibabaCloud\Oss\V2 as Oss;

// 解析命令行参数的描述定义
$optsdesc = [
    "region" => ['help' => 'The region in which the bucket is located.', 'required' => True],
    "endpoint" => ['help' => 'The domain names that other services can use to access OSS.', 'required' => False],
    "bucket" => ['help' => 'The name of the bucket', 'required' => True],
];

// 将参数键转换为 getopt 所需的格式（如："region:"）
$longopts = \array_map(function ($key) {
    return "$key:";
}, array_keys($optsdesc));

// 获取命令行传入的长选项参数
$options = getopt("", $longopts);

// 遍历所有参数定义，检查必填项是否都已提供
foreach ($optsdesc as $key => $value) {
    // 如果是必填项且未提供，则输出错误信息并退出
    if ($value['required'] === True && empty($options[$key])) {
        $help = $value['help'];
        echo "Error: the following arguments are required: --$key, $help";
        exit(1);
    }
}

// 提取命令行参数中的 region 和 bucket 名称
$region = $options["region"];
$bucket = $options["bucket"];

// 从环境变量中加载访问凭证（如 OSS_ACCESS_KEY_ID 和 OSS_ACCESS_KEY_SECRET）
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

// 加载 SDK 默认配置
$cfg = Oss\Config::loadDefault();

// 设置凭证、区域以及可选的自定义 Endpoint
$cfg->setCredentialsProvider($credentialsProvider);
$cfg->setRegion($region);
if (isset($options["endpoint"])) {
    $cfg->setEndpoint($options["endpoint"]);
}

// 创建 OSS 客户端实例
$client = new Oss\Client($cfg);

// 构建 GetBucketReplication 请求对象
$request = new Oss\Models\GetBucketReplicationRequest(bucket: $bucket);

// 发送请求并获取响应结果
$result = $client->getBucketReplication($request);

// 输出响应的状态码、请求 ID 和复制规则
printf(
    'status code:' . $result->statusCode . PHP_EOL .
    'request id:' . $result->requestId . PHP_EOL .
    'replication config:' . var_export($result->replicationConfiguration, true)
);

设置数据复制时间控制（RTC）

以下代码用于为已有的跨区域复制规则开启或关闭数据复制时间控制（RTC）功能。

<?php

// 引入 Composer 的自动加载文件，用于加载 SDK 和依赖类
require_once __DIR__ . '/../vendor/autoload.php';

// 使用 Alibaba Cloud OSS V2 命名空间，并简写为 Oss
use AlibabaCloud\Oss\V2 as Oss;

// 定义命令行参数及其说明和是否必填
$optsdesc = [
    "region" => ['help' => 'The region in which the bucket is located.', 'required' => True],
    "endpoint" => ['help' => 'The domain names that other services can use to access OSS.', 'required' => False],
    "bucket" => ['help' => 'The name of the bucket', 'required' => True],
    "rule-id" => ['help' => 'The replication rule id of the bucket', 'required' => True],
];

// 将参数键转换为 getopt 所需的格式（带冒号表示需要值）
$longopts = \array_map(function ($key) {
    return "$key:";
}, array_keys($optsdesc));

// 获取命令行传入的长选项参数
$options = getopt("", $longopts);

// 检查所有必填参数是否都已提供
foreach ($optsdesc as $key => $value) {
    if ($value['required'] === True && empty($options[$key])) {
        $help = $value['help'];
        echo "Error: the following arguments are required: --$key, $help";
        exit(1);
    }
}

// 提取命令行参数中的 region、bucket 和 rule-id
$region = $options["region"];
$bucket = $options["bucket"];
$ruleId = $options["rule-id"];

// 从环境变量中加载访问凭证（如 OSS_ACCESS_KEY_ID 和 OSS_ACCESS_KEY_SECRET）
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

// 加载 SDK 默认配置
$cfg = Oss\Config::loadDefault();

// 设置凭证提供者、区域和可选的自定义 Endpoint
$cfg->setCredentialsProvider($credentialsProvider);
$cfg->setRegion($region);
if (isset($options["endpoint"])) {
    $cfg->setEndpoint($options["endpoint"]);
}

// 创建 OSS 客户端实例
$client = new Oss\Client($cfg);

// 构建 PutBucketRtcRequest 请求对象
$request = new Oss\Models\PutBucketRtcRequest(
    bucket: $bucket,
    rtcConfiguration: new Oss\Models\RtcConfiguration(
        rtc: new Oss\Models\ReplicationTimeControl(
            status: 'disabled' // 禁用 RTC 功能
        ),
        id: $ruleId // 指定要修改的复制规则ID
    )
);

$result = $client->putBucketRtc($request);

// 输出响应的状态码和请求ID
printf(
    'status code:' . $result->statusCode . PHP_EOL .
    'request id:' . $result->requestId
);

查看可复制的目标地域

以下代码用于查看Bucket的数据可复制的目标地域列表。

<?php

// 引入 Composer 自动加载文件，确保 SDK 和依赖类可以被正确加载
require_once __DIR__ . '/../vendor/autoload.php';

// 使用 Alibaba Cloud OSS V2 命名空间，并简写为 Oss
use AlibabaCloud\Oss\V2 as Oss;

// 定义命令行参数及其说明和是否必填
$optsdesc = [
    "region" => ['help' => 'The region in which the bucket is located.', 'required' => True],
    "endpoint" => ['help' => 'The domain names that other services can use to access OSS.', 'required' => False],
    "bucket" => ['help' => 'The name of the bucket', 'required' => True],
];

// 将参数键转换为 getopt 所需的格式，如 "region:"
$longopts = \array_map(function ($key) {
    return "$key:";
}, array_keys($optsdesc));

// 获取命令行传入的长选项参数
$options = getopt("", $longopts);

// 遍历参数定义，检查所有必填项是否已提供
foreach ($optsdesc as $key => $value) {
    if ($value['required'] === True && empty($options[$key])) {
        $help = $value['help'];
        echo "Error: the following arguments are required: --$key, $help";
        exit(1);
    }
}

// 提取命令行参数中的 region 和 bucket 名称
$region = $options["region"];
$bucket = $options["bucket"];

// 从环境变量中加载访问凭证（如 OSS_ACCESS_KEY_ID 和 OSS_ACCESS_KEY_SECRET）
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

// 加载 SDK 默认配置
$cfg = Oss\Config::loadDefault();

// 设置凭证提供者、区域和可选的自定义 Endpoint
$cfg->setCredentialsProvider($credentialsProvider);
$cfg->setRegion($region);
if (isset($options["endpoint"])) {
    $cfg->setEndpoint($options["endpoint"]);
}

// 创建 OSS 客户端实例
$client = new Oss\Client($cfg);

// 构建 GetBucketReplicationLocation 请求对象，用于获取可用的复制目标区域列表
$request = new Oss\Models\GetBucketReplicationLocationRequest(bucket: $bucket);

// 发送请求并获取响应结果
$result = $client->getBucketReplicationLocation($request);

// 输出响应的状态码、请求 ID 和返回的复制区域信息
printf(
    'status code:' . $result->statusCode . PHP_EOL .
    'request id:' . $result->requestId . PHP_EOL .
    'replication location:' . var_export($result->replicationLocation, true)
);

查看数据复制进度

说明

数据复制进度分为历史数据复制进度和新写入数据复制进度。

历史数据复制进度用百分比表示，仅对开启了历史数据复制的存储空间有效。
新写入数据复制进度用新写入数据的时间点表示，代表这个时间点之前的数据已复制完成。

以下代码用于查看Bucket中指定规则ID的数据复制进度。

<?php

// 引入 Composer 自动加载文件，用于加载 SDK 和依赖类
require_once __DIR__ . '/../vendor/autoload.php';

// 使用 Alibaba Cloud OSS V2 命名空间，并简写为 Oss
use AlibabaCloud\Oss\V2 as Oss;

// 定义命令行参数及其说明和是否必填
$optsdesc = [
    "region" => ['help' => 'The region in which the bucket is located.', 'required' => True],
    "endpoint" => ['help' => 'The domain names that other services can use to access OSS.', 'required' => False],
    "bucket" => ['help' => 'The name of the bucket', 'required' => True],
    "rule-id" => ['help' => 'The replication rule id of the bucket', 'required' => True],
];

// 将参数键转换为 getopt 所需的格式（带冒号表示需要值）
$longopts = \array_map(function ($key) {
    return "$key:";
}, array_keys($optsdesc));

// 获取命令行传入的长选项参数
$options = getopt("", $longopts);

// 遍历参数定义，检查所有必填项是否已提供
foreach ($optsdesc as $key => $value) {
    if ($value['required'] === True && empty($options[$key])) {
        $help = $value['help'];
        echo "Error: the following arguments are required: --$key, $help";
        exit(1);
    }
}

// 提取命令行参数中的 region、bucket 和 rule-id
$region = $options["region"];
$bucket = $options["bucket"];
$ruleId = $options["rule-id"];

// 从环境变量中加载访问凭证（如 OSS_ACCESS_KEY_ID 和 OSS_ACCESS_KEY_SECRET）
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

// 加载 SDK 默认配置
$cfg = Oss\Config::loadDefault();

// 设置凭证提供者、区域和可选的自定义 Endpoint
$cfg->setCredentialsProvider($credentialsProvider);
$cfg->setRegion($region);
if (isset($options["endpoint"])) {
    $cfg->setEndpoint($options["endpoint"]);
}

// 创建 OSS 客户端实例
$client = new Oss\Client($cfg);

// 构建 GetBucketReplicationProgress 请求对象，用于查询指定复制规则的同步进度
$request = new Oss\Models\GetBucketReplicationProgressRequest(bucket: $bucket, ruleId: $ruleId);

// 发送请求并获取复制进度信息
$result = $client->getBucketReplicationProgress($request);

// 输出响应的状态码、请求 ID和复制进度详情
printf(
    'status code:' . $result->statusCode . PHP_EOL .
    'request id:' . $result->requestId . PHP_EOL .
    'replication progress:' . var_export($result->replicationProgress, true)
);

关闭数据复制

通过删除存储空间的复制规则，您可以关闭源存储空间到目标存储空间的数据复制关系。

以下代码用于删除Bucket中指定规则ID的数据复制关系。

<?php

// 引入 Composer 自动加载文件，确保 SDK 和依赖类能够正确加载
require_once __DIR__ . '/../vendor/autoload.php';

// 使用 Alibaba Cloud OSS V2 命名空间，并简写为 Oss
use AlibabaCloud\Oss\V2 as Oss;

// 定义命令行参数及其说明和是否必填
$optsdesc = [
    "region" => ['help' => 'The region in which the bucket is located.', 'required' => True],
    "endpoint" => ['help' => 'The domain names that other services can use to access OSS.', 'required' => False],
    "bucket" => ['help' => 'The name of the bucket', 'required' => True],
    "rule-id" => ['help' => 'The replication rule id of the bucket', 'required' => True],
];

// 将参数键转换为 getopt 所需的格式（带冒号表示需要值）
$longopts = \array_map(function ($key) {
    return "$key:";
}, array_keys($optsdesc));

// 获取命令行传入的长选项参数
$options = getopt("", $longopts);

// 遍历参数定义，检查所有必填项是否已提供
foreach ($optsdesc as $key => $value) {
    if ($value['required'] === True && empty($options[$key])) {
        $help = $value['help'];
        echo "Error: the following arguments are required: --$key, $help";
        exit(1);
    }
}

// 提取命令行参数中的 region、bucket 和 rule-id
$region = $options["region"];
$bucket = $options["bucket"];
$ruleId = $options["rule-id"];

// 从环境变量中加载访问凭证（如 OSS_ACCESS_KEY_ID 和 OSS_ACCESS_KEY_SECRET）
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

// 加载 SDK 默认配置
$cfg = Oss\Config::loadDefault();

// 设置凭证提供者、区域以及可选的自定义 Endpoint
$cfg->setCredentialsProvider($credentialsProvider);
$cfg->setRegion($region);
if (isset($options["endpoint"])) {
    $cfg->setEndpoint($options["endpoint"]);
}

// 创建 OSS 客户端实例
$client = new Oss\Client($cfg);

// 构建 DeleteBucketReplication 请求对象，用于删除指定复制规则
$request = new Oss\Models\DeleteBucketReplicationRequest(
    bucket: $bucket,
    replicationRules: new Oss\Models\ReplicationRules(
        ids: [$ruleId] // 指定要删除的复制规则 ID 列表
    )
);

// 发送请求以删除指定的复制规则
$result = $client->deleteBucketReplication($request);

// 输出响应的状态码和请求 ID
printf(
    'status code:' . $result->statusCode . PHP_EOL .
    'request id:' . $result->requestId
);