# 复制对象(HarmonyOS SDK) #### 功能说明用户可以根据需要将存储在OBS上的对象复制到其他路径下。复制对象操作将创建需要复制的对象的副本。在单次操作中，您可以创建最大5GB的对象副本。为指定桶中的对象创建一个副本。 #### 接口约束 - 您必须是桶拥有者或拥有复制对象的权限，才能复制对象。建议使用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与Endpoint的对应关系，详细信息请参见[地区与终端节点](https://developer.huaweicloud.com/endpoint?OBS)。 - 复制对象操作的请求需要通过头域携带复制的源桶和对象信息，不能携带消息实体。 - 目标对象大小范围是\[0, 5GB\]，如果源对象大小超过5GB，只能使用[多段相关接口(HarmonyOS SDK)](https://support.huaweicloud.com/sdk-harmony-devg-obs/obs_34_0621.html)功能复制部分对象。 #### 方法定义 ``` copyObject(input: CopyObjectInput): Response ``` #### 请求参数表1请求参数列表 | **参数名称** | **参数类型** | **是否必选** | **描述** | |:---|:---|:---|:---| | input | [CopyObjectInput] | 必选 | **参数解释：** 复制对象接口入参，详见[CopyObjectInput]。 | 表2CopyObjectInput | **参数名称** | **参数类型** | **是否必选** | **描述** | |:---|:---|:---|:---| | 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参数指定版本源对象。示例：source_bucket/sourceObject?versionId=G001117FCE89978B0000401205D5DC9A。 **约束限制：** 中文字符与%，需要进行URL编码。 **默认取值：** 无 | | Acl | [AclType] | 可选 | **参数解释：** 复制对象时可指定的预定义ACL。有关访问控制列表（Access Control List，ACL）功能的详细信息可参见[ACL功能介绍](https://support.huaweicloud.com/perms-cfg-obs/obs_40_0005.html)。 **取值范围：** 可选择的配置选项参见[AclType]。 **默认取值：** 无 | | MetadataDirective | [MetadataDirectiveType] | 可选 | **参数解释：** 复制源对象属性的策略。 **取值范围：** 可选择的对象属性选项参见[MetadataDirectiveType]。 **默认取值：** 无 | | CopySourceIfMatch | string | 可选 | **参数解释：** 如果源对象的ETag值与该参数值相同，则进行复制，否则返回错误。 **默认取值：** 无 | | CopySourceIfNoneMatch | string | 可选 | **参数解释：** 如果源对象的ETag值与该参数值不相同，则进行复制，否则返回错误。 **默认取值：** 无 | | CopySourceIfUnmodifiedSince | string | 可选 | **参数解释：** 如果源对象在指定的时间后没有修改，则进行复制，否则抛出异常。 **默认取值：** 无 | | CopySourceIfModifiedSince | string | 可选 | **参数解释：** 如果源对象在指定的时间后有修改，则进行复制，否则抛出异常。 **默认取值：** 无 | | WebsiteRedirectLocation | string | 可选 | **参数解释：** 当桶设置了Website配置，可以将获取这个对象的请求重定向到桶内另一个对象或一个外部的URL。例如，重定向请求到桶内另一对象： WebsiteRedirectLocation:/anotherPage.html 或重定向请求到一个外部URL： WebsiteRedirectLocation:http://www.example.com/ OBS将这个值从头域中取出，保存在对象的元数据"WebsiteRedirectLocation"中。 **约束限制：** - 必须以"/"、"http://"或"https://"开头，长度不超过2KB。 - OBS仅支持为桶根目录下的对象设置重定向，不支持为桶中文件夹下的对象设置重定向。 **默认取值：** 无 | | CopySourceSseC | string | 可选 | **参数解释：** 指定解密源对象使用的算法。 **约束限制：** - 仅在SSE-C加密方式下使用该头域。 **默认取值：** 无 | | CopySourceSseCKey | string | 可选 | **参数解释：** 解密源对象使用的密钥。 **约束限制：** - 仅在SSE-C加密方式下使用该头域。 - 该值由256-bit的密钥需要经过base64-encoded得到。 **默认取值：** 无 | | CacheControl | string | 可选 | **参数解释：** 复制时重写响应中的Cache-Control头。 **默认取值：** 无 | | ContentDisposition | string | 可选 | **参数解释：** 复制时重写响应中的Content-Disposition头。 **默认取值：** 无 | | ContentEncoding | string | 可选 | **参数解释：** 复制时重写响应中的Content-Encoding头。 **默认取值：** 无 | | ContentLanguage | string | 可选 | **参数解释：** 复制时重写响应中的Content-Language头。 **默认取值：** 无 | | ContentType | string | 可选 | **参数解释：** 复制时重写响应中的Content-Type头。 **默认取值：** 无 | | Expires | string | 可选 | **参数解释：** 复制时重写响应中的Expires头。 **默认取值：** 无 | | StorageClass | [StorageClassType] | 可选 | **参数解释：** 复制时设置对象的存储类型。 **取值范围：** 可选择的存储类型参见[StorageClassType]。 **默认取值：** 无，如果未设置此头域，则对象的存储类型默认为桶的存储类型。 | | Metadata | object | 可选 | **参数解释：** 目标对象的自定义元数据。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。 **默认取值：** 无 | | GrantRead | string | 可选 | **参数解释** **：** 被授予READ权限的账号的账号ID，即domain_id。账号被授予READ权限后，针对当前正在复制的对象，允许获取对象的内容、获取对象的元数据。 **取值范围：** 如何获取账号ID请参见[如何获取账号ID和用户ID？(HarmonyOS SDK)](https://support.huaweicloud.com/sdk-harmony-devg-obs/obs_34_0605.html)。 **默认取值：** 无 | | GrantReadAcp | string | 可选 | **参数解释** **：** 被授予READ_ACP权限的账号的账号ID，即domain_id。账号被授予READ_ACP权限后，针对当前正在复制的对象，允许读对象的ACL信息。 **取值范围：** 如何获取账号ID请参见[如何获取账号ID和用户ID？(HarmonyOS SDK)](https://support.huaweicloud.com/sdk-harmony-devg-obs/obs_34_0605.html) **默认取值：** 无 | | GrantWriteAcp | string | 可选 | **参数解释** **：** 被授予WRITE_ACP权限的账号的账号ID，即domain_id。账号被授予WRITE_ACP权限后，针对当前正在复制的对象，允许修改对象的ACL信息。 **取值范围：** 如何获取账号ID请参见[如何获取账号ID和用户ID？(HarmonyOS SDK)](https://support.huaweicloud.com/sdk-harmony-devg-obs/obs_34_0605.html) **默认取值：** 无 | | GrantFullControl | string | 可选 | **参数解释** **：** 被授予FULL_CONTROL权限的账号的账号ID，即domain_id。账号被授予FULL_CONTROL权限后，针对当前正在复制的对象，允许进行任何操作，读对象、获取对象元数据、获取对象ACL、写对象ACL。 **取值范围：** 如何获取账号ID请参见[如何获取账号ID和用户ID？(HarmonyOS SDK)](https://support.huaweicloud.com/sdk-harmony-devg-obs/obs_34_0605.html) **默认取值：** 无 | | SuccessActionRedirect | string | 可选 | **参数解释：** 此参数的值是一个URL，用于指定当此次请求操作成功响应后的重定向的地址。如果此参数值有效且操作成功，响应码为303，Location头域由此参数以及桶名、对象名、对象的ETag组成。如果此参数值无效，则OBS忽略此参数的作用，Location头域为对象地址，响应码根据操作成功或失败正常返回。 **默认取值：** 无 | 表3AclType | **常量名** | **原始值** | **说明** | |:---|:---|:---| | PRIVATE | private | 私有读写。桶或对象的所有者拥有完全控制的权限，其他任何人都没有访问权限。 | | PUBLIC_READ | public-read | 公共读私有写。设在桶上，所有人可以获取该桶内对象列表、桶内多段任务、桶的元数据、桶的多版本。设在对象上，所有人可以获取该对象内容和元数据。 | | PUBLIC_READ_WRITE | public-read-write | 公共读写。设在桶上，所有人可以获取该桶内对象列表、桶内多段任务、桶的元数据、桶的多版本、上传对象、删除对象、初始化段任务、上传段、合并段、复制段、取消多段上传任务。设在对象上，所有人可以获取该对象内容和元数据。 | | PUBLIC_READ_DELIVERED | public-read-delivered | 桶公共读，桶内对象公共读。设在桶上，所有人可以获取该桶内对象列表、桶内多段任务、桶的元数据、桶的多版本，可以获取该桶内对象的内容和元数据。说明： AclPublicReadDelivered不能应用于对象。 | | PUBLIC_READ_WRITE_DELIVERED | public-read-write-delivered | 桶公共读写，桶内对象公共读写。设在桶上，所有人可以获取该桶内对象列表、桶内多段任务、桶的元数据、桶的多版本、上传对象、删除对象、初始化段任务、上传段、合并段、复制段、取消多段上传任务，可以获取该桶内对象的内容和元数据。说明： AclPublicReadWriteDelivered不能应用于对象。 | | BUCKET_OWNER_FULL_CONTROL | bucket-owner-full-control | 设在对象上，桶和对象的所有者拥有对象的完全控制权限，其他任何人都没有访问权限。默认情况下，上传对象至其他用户的桶中，桶拥有者没有对象的控制权限。对象拥有者为桶拥有者添加此权限控制策略后，桶所有者可以完全控制对象。例如，用户A上传对象x至用户B的桶中，系统默认用户B没有对象x的控制权。当用户A为对象x设置bucket-owner-full-control策略后，用户B就拥有了对象x的控制权。 | 表4MetadataDirectiveType | **常量名** | **原始值** | **说明** | |:---|:---|:---| | COPY | COPY | 复制对象时，复制源对象属性。须知：该值仅在[复制对象(HarmonyOS SDK)](https://support.huaweicloud.com/sdk-harmony-devg-obs/obs_34_0405.html)接口中使用。 | | REPLACE | REPLACE | 使用当前请求中携带的头域完整替换，未指定的元数据会被删除。 | | REPLACE_NEW | REPLACE_NEW | 对于已经存在值的元数据进行替换，不存在值的元数据进行赋值，未指定的元数据保持不变。须知：该值仅在[设置对象元数据(HarmonyOS SDK)](https://support.huaweicloud.com/sdk-harmony-devg-obs/obs_34_0408.html)接口中使用。 | 表5StorageClassType | **常量名** | **原始值** | **说明** | |:---|:---|:---| | STANDARD | STANDARD | 标准存储。标准存储拥有低访问时延和较高的吞吐量，适用于有大量热点对象（平均一个月多次）或小对象（\<1MB），且需要频繁访问数据的业务场景。 | | WARM | WARM | 低频访问存储。低频访问存储适用于不频繁访问（平均一年少于12次）但在需要时也要求能够快速访问数据的业务场景。 | | COLD | COLD | 归档存储。归档存储适用于很少访问（平均一年访问一次）数据的业务场景。 | | DEEP_ARCHIVE | DEEP_ARCHIVE | 深度归档存储。适用于长期不访问（平均几年访问一次）数据的业务场景。 | ![](https://support.huaweicloud.com/sdk-harmony-devg-obs/public_sys-resources/note_3.0-zh-cn.png) - 如果包含CopySourceIfUnmodifiedSince并且不符合，或者包含CopySourceIfMatch并且不符合，或者包含CopySourceIfModifiedSince并且不符合，或者包含CopySourceIfNoneMatch并且不符合，抛出异常中HTTP状态码为：412 precondition failed。 - CopySourceIfModifiedSince和CopySourceIfNoneMatch可以一起使用；CopySourceIfUnmodifiedSince和CopySourceIfMatch可以一起使用。 #### 返回结果表6返回结果 | **参数类型** | **描述** | |:---|:---| | [Response]。说明：该接口返回一个Promise类型，需要使用Promise、async/await语法处理。 | **参数解释：** 接口返回信息，详见[Response]。 | 表7Response | **参数名称** | **参数类型** | **描述** | |:---|:---|:---| | CommonMsg | [ICommonMsg] | **参数解释：** 接口调用完成后的公共信息，包含HTTP状态码，操作失败的错误码等，详见[ICommonMsg]。 | | InterfaceResult | [CopyObjectOutput] | **参数解释：** 操作成功后的结果数据，详见[CopyObjectOutput]。 **约束限制：** 当Status大于300时为空。 | 表8ICommonMsg | **参数名称** | **参数类型** | **描述** | |:---|:---|:---| | Status | number | **参数解释：** OBS服务端返回的HTTP状态码。 **取值范围：** 状态码是一组从2xx（成功）到4xx或5xx（错误）的数字代码，状态码表示了请求响应的状态。完整的状态码列表请参见[状态码](https://support.huaweicloud.com/api-obs/obs_04_0114.html)。 | | Code | string | **参数解释：** OBS服务端返回的错误码。 | | Message | string | **参数解释：** OBS服务端返回的错误描述。 | | HostId | string | **参数解释：** OBS服务端返回的请求服务端ID。 | | RequestId | string | **参数解释：** OBS服务端返回的请求ID。 | | Id2 | string | **参数解释：** OBS服务端返回的请求ID2。 | | Indicator | string | **参数解释：** OBS服务端返回的详细错误码。 | 表9CopyObjectOutput | **参数名称** | **参数类型** | **描述** | |:---|:---|:---| | RequestId | string | **参数解释：** OBS服务端返回的请求ID。 **默认取值：** 无 | | LastModified | string | **参数解释：** 目标对象的最近一次修改时间（UTC时间）。 **约束限制：** 日期格式必须为ISO8601的格式。例如：2018-01-01T00:00:00.000Z，表示最后一次修改时间为2018-01-01T00:00:00.000Z。 **默认取值：** 无 | | ETag | string | **参数解释：** 目标对象的ETag值。对象的base64编码的128位MD5摘要。ETag是对象内容的唯一标识，可以通过该值识别对象内容是否有变化。比如上传对象时ETag为A，下载对象时ETag为B，则说明对象内容发生了变化。ETag只反映变化的内容，而不是其元数据。上传的对象或复制操作创建的对象，都有唯一的ETag。 **约束限制：** 当对象是服务端加密的对象时，ETag值不是对象的MD5值。 **取值范围：** 长度为32的字符串。 **默认取值：** 无 | | CopySourceVersionId | string | **参数解释：** 源对象的版本号。 **取值范围：** 长度为32的字符串。 **默认取值：** 无 | | VersionId | string | **参数解释：** 目标对象的版本号。 **取值范围：** 长度为32的字符串。 **默认取值：** 无 | #### 代码示例本示例用于复制源sourcebucketname桶中的sourceobjectkey对象到目标桶examplebucket桶中的example/objectname对象。 ``` // 引入依赖包 import ObsClient, { CopyObjectInput } from '@obs/esdk-obs-harmony'; import { process } from '@kit.ArkTS'; import { BusinessError } from '@kit.BasicServicesKit'; import { hilog } from '@kit.PerformanceAnalysisKit'; const processManager = new process.ProcessManager(); // 创建ObsClient实例 const obsClient = new ObsClient({ // 推荐通过环境变量获取AKSK，这里也可以使用其他外部引入方式传入，如果使用硬编码可能会存在泄露风险 // 您可以登录访问管理控制台获取访问密钥AK/SK，获取方式请参见https://support.huaweicloud.com/usermanual-ca/ca_01_0003.html AccessKeyId: processManager.getEnvironmentVar("ACCESS_KEY_ID"), SecretAccessKey: processManager.getEnvironmentVar("SECRET_ACCESS_KEY"), // 【可选】如果使用临时AK/SK和SecurityToken访问OBS，同样建议您尽量避免使用硬编码，以降低信息泄露风险。您可以通过环境变量获取访问密钥AK/SK，也可以使用其他外部引入方式传入 // SecurityToken: processManager.getEnvironmentVar("SECURITY_TOKEN"), // Server填写Bucket对应的Endpoint, 这里以华北-北京四为例，其他地区请按实际情况填写 Server: "https://obs.cn-north-4.myhuaweicloud.com", }); async function copyObject() { try { const params: CopyObjectInput = { // 指定目标桶名称 Bucket: "examplebucket", // 指定目标对象，此处以 example/objectname 为例 Key: 'example/objectname', // 指定复制源桶名和对象名，此处复制源桶名以sourcebucketname为例，复制源对象名以sourceobjectkey为例 CopySource: 'sourcebucketname/sourceobjectname' }; // 复制对象 const result = await obsClient.copyObject(params); if (result.CommonMsg.Status < 300) { hilog.info(0x0001, 'OBS-Harmony', "Copy Object(bucket:%s, object: %s) successful from bucket/object: %s!", params.Bucket, params.Key, params.CopySource); hilog.info(0x0001, 'OBS-Harmony', "RequestId: %s", result.CommonMsg.RequestId); hilog.info(0x0001, 'OBS-Harmony', "ETag: %s, LastModified:%s", result.InterfaceResult.ETag, result.InterfaceResult.LastModified); return; } hilog.error(0x0001, 'OBS-Harmony', "An ObsError was found, which means your request sent to OBS was rejected with an error response."); hilog.error(0x0001, 'OBS-Harmony', "Status: %d", result.CommonMsg.Status); hilog.error(0x0001, 'OBS-Harmony', "Code: %s", result.CommonMsg.Code); hilog.error(0x0001, 'OBS-Harmony', "Message: %s", result.CommonMsg.Message); hilog.error(0x0001, 'OBS-Harmony', "RequestId: %s", result.CommonMsg.RequestId); } catch (error) { const err = error as BusinessError; hilog.error(0x0001, 'OBS-Harmony', 'An Exception occurred: code=%d, message: %s', err.code, err.message); } } copyObject(); ``` #### 相关链接 - 关于复制对象的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)。