# 复制对象 #### 功能说明 用户可以根据需要将存储在OBS上的对象复制到其他路径下。复制对象操作将创建需要复制的对象的副本。在单次操作中，您可以创建最大5GB的对象副本。 为指定桶中的对象创建一个副本。 ![](https://support.huaweicloud.com/sdk-php-devg-obs/public_sys-resources/notice_3.0-zh-cn.png) 开发过程中，您有任何问题可以在GitHub上[提交issue](https://github.com/huaweicloud/huaweicloud-sdk-php-obs/issues)，或者在[华为云对象存储服务论坛](https://bbs.huaweicloud.com/forum/forum-620-1.html)中发帖求助。[接口参考文档](https://support.huaweicloud.com/api-obs_php_sdk_api_zh/obs_38_0001.html)详细介绍了每个接口的参数和使用方法。 #### 接口约束 - 您必须是桶拥有者或拥有复制对象的权限，才能复制对象。建议使用IAM或桶策略进行授权，如果使用IAM则需授予obs:object:PutObject权限，如果使用桶策略则需授予PutObject权限。相关授权方式介绍可参见[OBS权限控制概述](https://support.huaweicloud.com/perms-cfg-obs/obs_40_0001.html)，配置方式详见[使用IAM自定义策略](https://support.huaweicloud.com/usermanual-obs/obs_03_0121.html)、[配置对象策略](https://support.huaweicloud.com/usermanual-obs/obs_03_0075.html)。 - 用户有待复制的源对象的读权限。 - OBS支持的region以及region与endPoint的对应关系，详细信息请参见[地区与终端节点](https://developer.huaweicloud.com/endpoint?OBS)。 - 复制对象操作的请求需要通过头域携带拷贝的源桶和对象信息，不能携带消息实体。 - 支持同区域跨桶复制，不支持跨区域复制。 - 目标对象大小范围是\[0，5GB\]，如果源对象大小超过5GB，只能使用[分段复制](https://support.huaweicloud.com/sdk-php-devg-obs/obs_28_0408.html)功能复制对象。 - 如果待复制的源对象是归档或深度归档存储类别，则必须先恢复源对象才能进行复制。 #### 方法定义 ``` ObsClient->copyObject(array $parameter) ``` #### 请求参数说明 表1请求参数列表 | **参数名称** | **参数类型** | **是否必选** | **描述** | |:---|:---|:---|:---| | Bucket | string | 必选 | **参数解释** **：** 目标桶名。 **约束限制：** - 桶的名称需全局唯一，不能与已有的任何桶名称重复，包括其他用户创建的桶。 - 桶命名规则如下： - 3～63个字符，数字或小写字母开头，支持小写字母、数字、"-"、"."。 - 禁止使用IP地址。 - 禁止以"-"或"."开头及结尾。 - 禁止两个"."相邻（如："my..bucket"）。 - 禁止"."和"-"相邻（如："my-.bucket"和"my.-bucket"）。 - 同一用户在同一个区域多次创建同名桶不会报错，创建的桶属性以第一次请求为准。 **默认取值：** 无 | | Key | string | 必选 | **参数解释：** 目标对象名。对象名是对象在存储桶中的唯一标识。对象名是对象在桶中的完整路径，路径中不包含桶名。 例如，您对象的访问地址为bucketname.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功能介绍](https://support.huaweicloud.com/perms-cfg-obs/obs_40_0005.html)。 **取值范围：** 如果使用预定义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 其中： - regionID是使用密钥所属region的ID，可在[地区和终端节点](https://developer.huaweicloud.com/endpoint?OBS)页面获取； - DomainID是使用密钥所属的账号ID，获取方法参见[如何获取账号ID和用户ID？](https://support.huaweicloud.com/sdk-php-devg-obs/obs_23_1712.html) - key_id是从数据加密服务创建的密钥ID，获取方法请参见[查看密钥](https://support.huaweicloud.com/usermanual-dew/dew_01_0179.html)。 **默认取值：** - 如果用户没有提供该头域，那么默认的主密钥将会被使用。 - 如果默认主密钥不存在，将默认创建并使用。 | | 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（错误）的数字代码，状态码表示了请求响应的状态。完整的状态码列表请参见[状态码](https://support.huaweicloud.com/api-obs/obs_04_0114.html)。 **默认取值：** 无 | | 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 其中： - regionID是使用密钥所属region的ID，可在[地区和终端节点](https://developer.huaweicloud.com/endpoint?OBS)页面获取； - DomainID是使用密钥所属的账号ID，获取方法参见[如何获取账号ID和用户ID？](https://support.huaweicloud.com/sdk-php-devg-obs/obs_23_1712.html) - key_id是从数据加密服务创建的密钥ID，获取方法请参见[查看密钥](https://support.huaweicloud.com/usermanual-dew/dew_01_0179.html)。 **默认取值：** - 如果用户没有提供该头域，那么默认的主密钥将会被使用。 - 如果默认主密钥不存在，将默认创建并使用。 | | SseC | string | 可选 **参数解释：** 表示服务端加密是SSE-C方式。对象使用SSE-C加密方式。 **取值范围：** 可选值：AES256，即选择SSE-C方式加密对象。 **默认取值：** 无 | | SseCKey | string | 可选 **参数解释：** SSE-C方式下加密使用的密钥，该密钥用于加密对象。 **约束限制：** 该头域由256bit的密钥经过Base64编码得到，示例：K7QkYpBkM5+hca27fsNkUnNVaobncnLht/rCB2o/9Cw= **默认取值：** 无 | #### 简单复制 以下代码展示了如何进行简单复制： ``` getenv('ACCESS_KEY_ID'), 'secret' => getenv('SECRET_ACCESS_KEY'), 'endpoint' => 'https://your-endpoint', 'signature' => 'obs' ]); try { $resp = $obsClient->copyObject ([ 'Bucket' => 'destbucket', 'Key' => 'destobjectname', 'CopySource' => 'sourcebucketname/sourceobjectname' ]); printf( "RequestId:%s\n", $resp['RequestId']); } catch (ObsException $e) { // 操作失败，获取详细异常信息 printf("CopyObjectFailed: Status:%d, Code:%s, Message:%s\n", $e->getStatusCode(), $e->getExceptionCode(), $e->getExceptionMessage()); } finally { $obsClient->close(); } ``` ![](https://support.huaweicloud.com/sdk-php-devg-obs/public_sys-resources/note_3.0-zh-cn.png) 使用**CopySource参数**指定复制时的源对象信息。 #### 重写对象属性 以下代码展示了如何在复制对象时重写对象属性： ``` getenv('ACCESS_KEY_ID'), 'secret' => getenv('SECRET_ACCESS_KEY'), 'endpoint' => 'https://your-endpoint', 'signature' => 'obs' ]); try { $resp = $obsClient->copyObject ([ 'Bucket' => 'destobjectname', 'Key' => 'destobjectname', 'CopySource' => 'sourcebucketname/sourceobjectname', 'ContentType' => 'image/jpeg', 'StorageClass' => ObsClient::StorageClassWarm, 'Metadata' => ['property' => 'property-value'], 'MetadataDirective' => ObsClient::ReplaceMetadata ]); printf( "RequestId:%s\n", $resp['RequestId']); } catch (ObsException $e) { // 操作失败，获取详细异常信息 printf("CopyObjectFailed: Status:%d, Code:%s, Message:%s\n", $e->getStatusCode(), $e->getExceptionCode(), $e->getExceptionMessage()); } finally { $obsClient->close(); } ``` ![](https://support.huaweicloud.com/sdk-php-devg-obs/public_sys-resources/note_3.0-zh-cn.png) 使用**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值与该参数值不相同，则进行复制，否则抛出异常。 | 字符串。 | ![](https://support.huaweicloud.com/sdk-php-devg-obs/public_sys-resources/note_3.0-zh-cn.png) - 源对象的ETag值是指源对象数据的MD5校验值。 - 如果包含CopySourceIfUnmodifiedSince并且不符合，或者包含CopySourceIfMatch并且不符合，或者包含CopySourceIfModifiedSince并且不符合，或者包含CopySourceIfNoneMatch并且不符合，则复制失败，抛出异常中HTTP状态码为：412 precondition failed。 - CopySourceIfModifiedSince和CopySourceIfNoneMatch可以一起使用；CopySourceIfUnmodifiedSince和CopySourceIfMatch可以一起使用。 以下代码展示了如何进行限定条件复制： ``` getenv('ACCESS_KEY_ID'), 'secret' => getenv('SECRET_ACCESS_KEY'), 'endpoint' => 'https://your-endpoint', 'signature' => 'obs' ]); try { $resp = $obsClient->copyObject ([ 'Bucket' => 'destobjectname', 'Key' => 'destobjectname', 'CopySource' => 'sourcebucketname/sourceobjectname', 'CopySourceIfModifiedSince' => 'Thu, 31 Dec 2015 16:00:00 GMT', 'CopySourceIfNoneMatch' => 'none-match-etag' ]); printf( "RequestId:%s\n", $resp['RequestId']); } catch (ObsException $e) { // 操作失败，获取详细异常信息 printf("CopyObjectFailed: Status:%d, Code:%s, Message:%s\n", $e->getStatusCode(), $e->getExceptionCode(), $e->getExceptionMessage()); } finally { $obsClient->close(); } ``` #### 重写对象ACL 以下代码展示了如何在复制对象时重写对象ACL： ``` getenv('ACCESS_KEY_ID'), 'secret' => getenv('SECRET_ACCESS_KEY'), 'endpoint' => 'https://your-endpoint', 'signature' => 'obs' ]); try { $resp = $obsClient->copyObject ([ 'Bucket' => 'destobjectname', 'Key' => 'destobjectname', 'CopySource' => 'sourcebucketname/sourceobjectname', // 复制时重写对象ACL为公共读 'ACL' => ObsClient::AclPublicRead ]);printf( "RequestId:%s\n", $resp['RequestId']); } catch (ObsException $e) { // 操作失败，获取详细异常信息 printf("CopyObjectFailed: Status:%d, Code:%s, Message:%s\n", $e->getStatusCode(), $e->getExceptionCode(), $e->getExceptionMessage()); } finally { $obsClient->close(); } ``` ![](https://support.huaweicloud.com/sdk-php-devg-obs/public_sys-resources/note_3.0-zh-cn.png) 使用**ACL参数**重写对象ACL。 #### 相关链接 - 关于复制对象的API说明，请参见[复制对象](https://support.huaweicloud.com/api-obs/obs_04_0082.html)。 - 复制对象过程中返回的错误码含义、问题原因及处理措施可参考[OBS错误码](https://support.huaweicloud.com/api-obs/obs_04_0115.html#section1)。 - 复制对象常见问题请参见[我可以在桶间进行文件复制吗？](https://support.huaweicloud.com/obs_faq/obs_faq_0056.html)。