文档首页/ 对象存储服务 OBS/ SDK参考/ PHP/ 管理对象/ 复制对象
更新时间：2026-01-06 GMT+08:00
查看PDF
分享

复制对象

功能说明

用户可以根据需要将存储在OBS上的对象复制到其他路径下。复制对象操作将创建需要复制的对象的副本。在单次操作中，您可以创建最大5GB的对象副本。

为指定桶中的对象创建一个副本。

开发过程中，您有任何问题可以在github上提交issue，或者在华为云对象存储服务论坛中发帖求助。接口参考文档详细介绍了每个接口的参数和使用方法。

接口约束

  • 您必须是桶拥有者或拥有复制对象的权限，才能复制对象。建议使用IAM或桶策略进行授权，如果使用IAM则需授予obs:object:PutObject权限，如果使用桶策略则需授予PutObject权限。相关授权方式介绍可参见OBS权限控制概述，配置方式详见使用IAM自定义策略、配置对象策略。
  • 用户有待复制的源对象的读权限。
  • OBS支持的region以及region与endPoint的对应关系，详细信息请参见地区与终端节点。
  • 复制对象操作的请求需要通过头域携带拷贝的源桶和对象信息，不能携带消息实体。
  • 支持同区域跨桶复制，不支持跨区域复制。
  • 目标对象大小范围是[0, 5GB]，如果源对象大小超过5GB，只能使用分段复制功能复制对象。
  • 如果待复制的源对象是归档或深度归档存储类别，则必须先恢复源对象才能进行复制。

方法定义

ObsClient->copyObject(array $parameter)

请求参数说明

表1 请求参数列表

参数名称

参数类型

是否必选

描述

Bucket

string

必选

参数解释：

目标桶名。

约束限制：

  • 桶的名字需全局唯一，不能与已有的任何桶名称重复，包括其他用户创建的桶。
  • 桶命名规则如下：
    • 3～63个字符，数字或字母开头，支持小写字母、数字、“-”、“.”。
    • 禁止使用IP地址。
    • 禁止以“-”或“.”开头及结尾。
    • 禁止两个“.”相邻（如：“my..bucket”）。
    • 禁止“.”和“-”相邻（如：“my-.bucket”和“my.-bucket”）。
  • 同一用户在同一个区域多次创建同名桶不会报错，创建的桶属性以第一次请求为准。

默认取值：

无

Key

string

必选

参数解释：

目标对象名。对象名是对象在存储桶中的唯一标识。对象名是对象在桶中的完整路径，路径中不包含桶名。

例如，您对象的访问地址为examplebucket.obs.cn-north-4.myhuaweicloud.com/folder/test.txt 中，对象名为folder/test.txt。

取值范围：

长度大于0且不超过1024的字符串。

默认取值：

无

CopySource

string

必选

参数解释：

指定源桶、源对象和源对象版本号（可为空）的参数。

约束限制：

格式：源桶名/源对象名?versionId=源对象版本号

默认取值：

无

ACL

string

可选

参数解释：

指定对象的ACL访问策略，您可以使用预定义的ACL，也可以自定义ACL，有关访问控制列表（Access Control List，ACL）功能的详细信息可参见ACL功能介绍。

取值范围：

如果使用预定义ACL，则可选配置项参见表2。

默认取值：

AccessControlList.REST_CANNED_PRIVATE

StorageClass

string

可选

参数解释：

复制时设置对象的存储类型。

取值范围：

可选择的存储类型参见表3。

默认取值：

无，如果未设置此头域，则对象的存储类型默认为桶的存储类型。

CopySourceIfMatch

string

可选

参数解释：

如果源对象的ETag值与该参数值相同，则进行复制，否则返回错误。

默认取值：

无

CopySourceIfNoneMatch

string

可选

参数解释：

如果源对象的ETag值与该参数值不相同，则进行复制，否则返回错误。

默认取值：

无

CopySourceIfUnmodifiedSince

string

或

\DateTime

可选

参数解释：

如果源对象在指定的时间后没有修改，则进行复制，否则抛出异常。

默认取值：

无

CopySourceIfModifiedSince

string

或

\DateTime

可选

参数解释：

如果源对象在指定的时间后有修改，则进行复制，否则抛出异常。

默认取值：

无

CacheControl

string

可选

参数解释：

复制时重写响应中的Cache-Control头。

默认取值：

无

ContentDisposition

string

可选

参数解释：

复制时重写响应中的Content-Disposition头。

默认取值：

无

ContentEncoding

string

可选

参数解释：

复制时重写响应中的Content-Encoding头。

默认取值：

无

ContentLanguage

string

可选

参数解释：

复制时重写响应中的Content-Language头。

默认取值：

无

ContentType

string

可选

参数解释：

复制时重写响应中的Content-Type头。

默认取值：

无

Expires

string

可选

参数解释：

复制时重写响应中的Expires头。

默认取值：

无

MetadataDirective

string

可选

参数解释：

复制源对象属性的策略。

取值范围：

可选择的对象属性选项参见表4。

默认取值：

无

Metadata

associative array

可选

参数解释：

目标对象的自定义元数据。OBS支持用户使用以“x-obs-meta-”开头的消息头来加入自定义的元数据，以便对对象进行自定义管理。当用户获取此对象或查询此对象元数据时，加入的自定义元数据将会在返回的消息头中出现。

约束限制：

  • 所有自定义元数据大小的总和不超过8K。单个自定义元数据大小的计算方式为：每个键和值的UTF-8 编码中的字节总数。
  • 自定义元数据的key值不区分大小写，OBS统一转为小写进行存储。value值区分大小写。
  • 自定义元数据key-value对都必须符合US-ASCII。如果一定要使用非ASCII码或不可识别字符，需要客户端自行做编解码处理，可以采用URL编码或者Base64编码，服务端不会做解码处理。例如x-obs-meta-中文：中文 经URL编码后发送，“中文”的URL编码为：%E4%B8%AD%E6%96%87，则响应为x-obs-meta-%E4%B8%AD%E6%96%87: %E4%B8%AD%E6%96%87

默认取值：

无

WebsiteRedirectLocation

string

可选

参数解释：

当桶设置了Website配置，可以将获取这个对象的请求重定向到桶内另一个对象或一个外部的URL。

例如，重定向请求到桶内另一对象：

WebsiteRedirectLocation:/anotherPage.html

或重定向请求到一个外部URL：

WebsiteRedirectLocation:http://www.example.com/

OBS将这个值从头域中取出，保存在对象的元数据“WebsiteRedirectLocation”中。

约束限制：

  • 必须以“/”、“http://”或“https://”开头，长度不超过2KB。
  • OBS仅支持为桶根目录下的对象设置重定向，不支持为桶中文件夹下的对象设置重定向。

默认取值：

无

SseKms

string

可选

参数解释：

表示服务端加密是SSE-KMS方式。对象使用SSE-KMS方式加密。

取值范围：

可选值：kms，即选择SSE-KMS方式加密对象。

默认取值：

无

SseKmsKey

string

可选

参数解释：

SSE-KMS加密方式下使用的KMS主密钥的ID值。

取值范围：

有效值支持两种格式：

  1. regionID:domainID(账号ID):key/key_id
  2. key_id

其中：

默认取值：

  • 如果用户没有提供该头域，那么默认的主密钥将会被使用。
  • 如果默认主密钥不存在，将默认创建并使用。

SseC

string

可选

参数解释：

表示服务端加密是SSE-C方式。对象使用SSE-C加密方式。

取值范围：

可选值：AES256，即选择SSE-C方式加密对象。

默认取值：

无

SseCKey

string

可选

参数解释：

SSE-C方式下加密使用的密钥，该密钥用于加密对象。

约束限制：

该头域由256bit的密钥经过Base64编码得到，示例：K7QkYpBkM5+hca27fsNkUnNVaobncnLht/rCB2o/9Cw=

默认取值：

无

CopySourceSseC

string

可选

参数解释：

表示服务端加密是SSE-C方式，对象使用SSE-C加密方式。

取值范围：

可选值：AES256，即选择SSE-C方式加密对象。

默认取值：

无

CopySourceSseCKey

string

可选

参数解释：

SSE-C方式下解密源对象的密钥，由AES256算法算出。

默认取值：

无
表2 预定义访问策略

访问方式

类型

说明

ObsClient::AclPrivate

string

私有读写。

ObsClient::AclPublicRead

string

公共读。

ObsClient::AclPublicReadWrite

string

公共读写。

ObsClient::AclPublicReadDelivered

string

桶公共读，桶内对象公共读。

ObsClient::AclPublicReadWriteDelivered

string

桶公共读写，桶内对象公共读写。
表3 存储类型

访问方式

类型

说明

ObsClient::StorageClassStandard

string

标准存储。

ObsClient::StorageClassWarm

string

低频访问存储。

ObsClient::StorageClassCold

string

归档存储。
表4 元数据复制策略

访问方式

类型

说明

ObsClient::CopyMetadata

string

复制元数据。

ObsClient::ReplaceMetadata

string

替换元数据。

返回结果说明

表5 返回结果

参数名称

参数类型

描述

HttpStatusCode

integer

参数解释：

HTTP状态码。

取值范围：

状态码是一组从2xx（成功）到4xx或5xx（错误）的数字代码，状态码表示了请求响应的状态。完整的状态码列表请参见状态码。

默认取值：

无

Reason

string

参数解释：

HTTP文本描述。

默认取值：

无

RequestId

string

参数解释：

OBS服务端返回的请求ID。

默认取值：

无

ETag

string

参数解释：

目标对象的ETag值。对象的base64编码的128位MD5摘要。ETag是对象内容的唯一标识，可以通过该值识别对象内容是否有变化。比如上传对象时ETag为A，下载对象时ETag为B，则说明对象内容发生了变化。ETag只反映变化的内容，而不是其元数据。上传的对象或拷贝操作创建的对象，都有唯一的ETag。

约束限制：

当对象是服务端加密的对象时，ETag值不是对象的MD5值。

取值范围：

长度为32的字符串。

默认取值：

无

LastModified

string

参数解释：

目标对象的最近一次修改时间（UTC时间）。

取值范围：

UTC时间

默认取值：

无

VersionId

string

参数解释：

目标对象的版本号。

取值范围：

长度为32的字符串。

默认取值：

无

CopySourceVersionId

string

参数解释：

源对象的版本号。

取值范围：

长度为32的字符串。

默认取值：

如果源桶未开启多版本状态则该值为空。

SseKms

string

可选

参数解释：

表示服务端加密是SSE-KMS方式。对象使用SSE-KMS方式加密。

取值范围：

可选值：kms，即选择SSE-KMS方式加密对象。

默认取值：

无

SseKmsKey

string

可选

参数解释：

SSE-KMS加密方式下使用的KMS主密钥的ID值。

取值范围：

有效值支持两种格式：

  1. regionID:domainID(账号ID):key/key_id
  2. key_id

其中：

默认取值：

  • 如果用户没有提供该头域，那么默认的主密钥将会被使用。
  • 如果默认主密钥不存在，将默认创建并使用。

SseC

string

可选

参数解释：

表示服务端加密是SSE-C方式。对象使用SSE-C加密方式。

取值范围：

可选值：AES256，即选择SSE-C方式加密对象。

默认取值：

无

SseCKey

string

可选

参数解释：

SSE-C方式下加密使用的密钥，该密钥用于加密对象。

约束限制：

该头域由256bit的密钥经过Base64编码得到，示例：K7QkYpBkM5+hca27fsNkUnNVaobncnLht/rCB2o/9Cw=

默认取值：

无

简单复制

以下代码展示了如何进行简单复制：

// 引入依赖库
require 'vendor/autoload.php';
// 使用源码安装时引入SDK代码库
// require 'obs-autoloader.php';
// 声明命名空间
use Obs\ObsClient;
// 创建ObsClient实例
$obsClient = new ObsClient ( [ 
      //推荐通过环境变量获取AKSK，这里也可以使用其他外部引入方式传入，如果使用硬编码可能会存在泄露风险。
      //您可以登录访问管理控制台获取访问密钥AK/SK，获取方式请参见https://support.huaweicloud.com/usermanual-ca/ca_01_0003.html
      'key' => getenv('ACCESS_KEY_ID'),
      'secret' => getenv('SECRET_ACCESS_KEY'),
      'endpoint' => 'https://your-endpoint',
      'signature' => 'obs'
] );

$resp = $obsClient->copyObject ( [ 
      'Bucket' => 'destbucketname',
      'Key' => 'destobjectname',
      'CopySource' => 'sourcebucketname/sourceobjectname'
] );
printf ( "RequestId:%s\n", $resp ['RequestId'] );

使用CopySource参数指定复制时的源对象信息。

重写对象属性

以下代码展示了如何在复制对象时重写对象属性：

// 引入依赖库
require 'vendor/autoload.php';
// 使用源码安装时引入SDK代码库
// require 'obs-autoloader.php';
// 声明命名空间
use Obs\ObsClient;
// 创建ObsClient实例
$obsClient = new ObsClient ( [ 
      //推荐通过环境变量获取AKSK，这里也可以使用其他外部引入方式传入，如果使用硬编码可能会存在泄露风险。
      //您可以登录访问管理控制台获取访问密钥AK/SK，获取方式请参见https://support.huaweicloud.com/usermanual-ca/ca_01_0003.html
      'key' => getenv('ACCESS_KEY_ID'),
      'secret' => getenv('SECRET_ACCESS_KEY'),
      'endpoint' => 'https://your-endpoint',
      'signature' => 'obs'
] );

$resp = $obsClient->copyObject ( [ 
       'Bucket' => 'destobjectname',
       'Key' => 'destobjectname',
       'CopySource' => 'sourcebucketname/soureobjectname',
       'ContentType' => 'image/jpeg',
       'StorageClass' => ObsClient::StorageClassWarm,
       'Metadata' => ['property' => 'property-value'],
       'MetadataDirective' => ObsClient::ReplaceMetadata
] );
printf ( "RequestId:%s\n", $resp ['RequestId'] );

使用Metadata参数指定待重写的自定义对象属性；使用MetadataDirective参数指定重写选项，支持ObsClient::ReplaceMetadata（重写）和ObsClient::CopyMetadata（从源对象复制）两个值。

限定条件复制

复制对象时，可以指定一个或多个限定条件，满足限定条件时则进行复制，否则抛出异常，复制对象失败。

您可以使用的限定条件如下：

参数

作用

格式

CopySourceIfModifiedSince

如果源对象在指定的时间后有修改，则进行复制，否则抛出异常。

符合http://www.ietf.org/rfc/rfc2616.txt规定格式的HTTP时间字符串。

CopySourceIfUnmodifiedSince

如果源对象在指定的时间后没有修改，则进行复制，否则抛出异常。

符合http://www.ietf.org/rfc/rfc2616.txt规定格式的HTTP时间字符串。

CopySourceIfMatch

如果源对象的ETag值与该参数值相同，则进行复制，否则抛出异常。

字符串。

CopySourceIfNoneMatch

如果源对象的ETag值与该参数值不相同，则进行复制，否则抛出异常。

字符串。
  • 源对象的ETag值是指源对象数据的MD5校验值。
  • 如果包含CopySourceIfUnmodifiedSince并且不符合，或者包含CopySourceIfMatch并且不符合，或者包含CopySourceIfModifiedSince并且不符合，或者包含CopySourceIfNoneMatch并且不符合，则复制失败，抛出异常中HTTP状态码为：412 precondition failed。
  • CopySourceIfModifiedSince和CopySourceIfNoneMatch可以一起使用；CopySourceIfUnmodifiedSince和CopySourceIfMatch可以一起使用。

以下代码展示了如何进行限定条件复制：

// 引入依赖库
require 'vendor/autoload.php';
// 使用源码安装时引入SDK代码库
// require 'obs-autoloader.php';
// 声明命名空间
use Obs\ObsClient;
// 创建ObsClient实例
$obsClient = new ObsClient ( [ 
      //推荐通过环境变量获取AKSK，这里也可以使用其他外部引入方式传入，如果使用硬编码可能会存在泄露风险。
      //您可以登录访问管理控制台获取访问密钥AK/SK，获取方式请参见https://support.huaweicloud.com/usermanual-ca/ca_01_0003.html
      'key' => getenv('ACCESS_KEY_ID'),
      'secret' => getenv('SECRET_ACCESS_KEY'),
      'endpoint' => 'https://your-endpoint',
      'signature' => 'obs'
] );

$resp = $obsClient->copyObject ( [ 
       'Bucket' => 'destobjectname',
       'Key' => 'destobjectname',
       'CopySource' => 'sourcebucketname/soureobjectname',
       'CopySourceIfModifiedSince' => 'Thu, 31 Dec 2015 16:00:00 GMT',    
       'CopySourceIfNoneMatch' => 'none-match-etag'
] );
printf ( "RequestId:%s\n", $resp ['RequestId'] );

重写对象ACL

以下代码展示了如何在复制对象时重写对象ACL：

// 引入依赖库
require 'vendor/autoload.php';
// 使用源码安装时引入SDK代码库
// require 'obs-autoloader.php';
// 声明命名空间
use Obs\ObsClient;
// 创建ObsClient实例
$obsClient = new ObsClient ( [ 
      //推荐通过环境变量获取AKSK，这里也可以使用其他外部引入方式传入，如果使用硬编码可能会存在泄露风险。
      //您可以登录访问管理控制台获取访问密钥AK/SK，获取方式请参见https://support.huaweicloud.com/usermanual-ca/ca_01_0003.html
      'key' => getenv('ACCESS_KEY_ID'),
      'secret' => getenv('SECRET_ACCESS_KEY'),
      'endpoint' => 'https://your-endpoint',
      'signature' => 'obs'
] );

$resp = $obsClient->copyObject ( [ 
       'Bucket' => 'destobjectname',
       'Key' => 'destobjectname',
       'CopySource' => 'sourcebucketname/soureobjectname',
       // 复制时重写对象ACL为公共读    
       'ACL' => ObsClient::AclPublicRead
] );
printf ( "RequestId:%s\n", $resp ['RequestId'] );

使用ACL参数重写对象ACL。

相关链接

父主题： 管理对象

相关文档