全部文档
当前文档
最近更新时间：2025-04-01 19:46:31
此PUT接口可以拷贝一个在KS3中已经存在的Object到某个Bucket。用户通过在请求中配置请求头部x-kss-copy-source来指定要拷贝的数据源。
用户必须对源Bucket的Object具有ks3:GetObject权限，对目标Bucket具有ks3:PutObject权限。
拷贝的源文件大小不能超过5GB，超过5GB时请使用Upload Part Copy接口进行分块拷贝。
目标桶和源桶必须在同一个Region。
支持跨账户复制，但用户需要具有拷贝对象的ks3:GetObject权限，以及目标空间的ks3:PutObject权限。
用户可以指定Object的存储类型，如果不指定，目标对象默认跟随目标Bucket的默认存储类型。
用户可以通过此接口实现对象移动、重命名、修改对象元数据和修改存储类型。
当源与目标为同一个桶且Key相同时，支持该接口实现对同一文件的修改存储类型与元数据的目的。
Object可修改的元数据包括 ：
HTTP Header头：Content-Type，Content-Length， Cache-Control， Content-Disposition， Content-Encoding，Expires
x-kss-meta-
如果复制的源文件带有标签，则需要对源文件有ks3:GetObject与ks3:GetObjectTagging权限，对目标文件有ks3:PutObject与ks3:PutObjectTagging权限。但是如果指定x-kss-tagging-directive为REPLACE且新指定Tag为空，则对目标文件只需有ks3:PutObject权限即可。
如果需要覆盖源文件对象标签，则x-kss-tagging-directive需设置为Replace且x-kss-tagging是合法值，此时x-kss-tagging指定的对象标签作为目标对象的新标签。若仅指定x-kss-tagging时，则无法完成重置目标对象的标签的覆盖。
PUT /{destinationObject} HTTP/1.1
Host: {destinationBucket}.{endpoint}
x-kss-copy-source: {/source_bucket/sourceObject}
Authorization: {SignatureValue}
Date: {date}注意：
该请求不使用请求参数。
该接口可以使用所有常用请求头部，此外，也可以使用下表所列请求头部。获取更多信息，请点击常用请求头部。
名称 | 描述 | 是否必选 |
|---|---|---|
x-kss-copy-source | 指定拷贝的源地址。格式为空间名称与对象的
| 是 |
x-kss-meta- | 用户元数据前缀标识。若某个头部前缀为x-kss-meta-，则为用户自定义元数据。
| 否 |
x-kss-metadata-directive | 指定是否拷贝源Object的元数据信息，有效值：COPY, REPLACE。如果此选项不指定，默认为COPY。 | 否 |
x-kss-storage-class | 设置存储类型。有关存储类型的详细介绍请参见文档：存储类型介绍。
| 否 |
x-kss-tagging | 指定目标Object对象标签，可同时设置多个标签，如：TagA=A&TagB=B。 | 否 |
x-kss-tagging-directive | 指定如何设置目标Object的对象标签。
| 否 |
x-kss-acl | 用于对象的预定义权限。
| 否 |
x-kss-copy-source-if-match | 条件复制参数，如果源
| 否 |
x-kss-copy-source-if-none-match | 条件复制参数，如果源
| 否 |
x-kss-copy-source-if-modified-since | 条件复制参数，如果源
| 否 |
x-kss-copy-source-if-unmodified-since | 条件复制参数，如果源
| 否 |
x-kss-forbid-overwrite | 源和目标不同Key复制时，同名文件是否覆盖上传，取值如下：
 当不带该请求头、携带该请求头但取值为空、携带该请求头并设置为true时，同名文件会报错。 | 否 |
x-kss-tagging | 指定Object的对象标签，可同时设置多个标签，如：TagA=A&TagB=B。 | 否 |
x-kss-tagging-directive | 指定如何设置目标Object的对象标签。
| 否 |
若在拷贝过程中选择加密，KS3拷贝加密支持如下场景：（1）若源Object未加密，支持对目标Object加密；（2）若源Object加密，目标Object可以选择不加密；（3）目标Object与源Object的加密方式可以不一致。详细加密方式描述如下。
若使用KS3托管密钥的服务器端加密，则需要使用以下请求头 。
名称 | 描述 | 是否必选 |
|---|---|---|
x-kss-server-side-encryption | 如果存储
| 是 |
若使用客户提供的加密密钥的服务器端加密，则需要使用以下请求头 。
名称 | 描述 | 是否必选 |
|---|---|---|
x-kss-server-side-encryption-customer-key | 由用户指定KS3加密时使用的
| 是 |
x-kss-server-side-encryption-customer-algorithm | 如果服务端使用了用户提供的加密秘钥加密，在请求解密时，响应将会包含该头部来确认使用的解密算法。
| 是 |
x-kss-server-side-encryption-customer-key-MD5 | 如果服务端使用了用户提供的加密秘钥加密，在请求解密时，响应将会包含该头部来提供用户提供加密秘钥的数据一致性验证信息。
| 是 |
x-kss-copy-source-server-side-encryption-customer-key | 由用户指定KS3解密时使用的
| 是 |
x-kss-copy-source-server-side-encryption-customer-algorithm | 指定数据源对象解密使用的解密算法。
| 是 |
x-kss-copy-source-server-side-encryption-customer-key-MD5 | 如果服务端使用了用户提供的加密秘钥加密，在请求解密时，响应将会包含该头部来提供用户提供加密秘钥的数据一致性验证信息。
| 是 |
该接口不使用请求内容。
该接口可以使用所有常用响应头部。获取更多信息，请点击常用响应头部。
名称 | 描述 |
|---|---|
x-kss-checksum-crc64ecma | Object的CRC64值，用于对象完整性校验。关于CRC64的计算标准，请参见：ECMA-182标准。
|
x-kss-server-side-encryption | 如果存储
|
x-kss-server-side-encryption-customer-algorithm | 如果服务端使用了用户提供的加密秘钥加密，在请求解密时，响应将会包含该头部来确认使用的解密算法。
|
x-kss-server-side-encryption-customer-key-MD5 | 如果服务端使用了用户提供的加密秘钥加密，在请求解密时，响应将会包含该头部来提供用户提供加密秘钥的数据一致性验证信息
|
名称 | 描述 |
|---|---|
CopyObjectResult | 响应内容的容器。
|
ETag | 返回一个新对象的实体标签。影响因素为对象的内容，与对象名称或元数据无关。
|
LastModified | 返回最后被修改的时间日期。
|
ChecksumCRC64ECMA | Object的CRC64值，用于对象完整性校验。关于CRC64的计算标准，请参见：ECMA-182标准。
|
该请求不返回任何特殊错误。
PUT /rename-image.jpg HTTP/1.1
Host: ks3-example.ks3-cn-beijing.ksyuncs.com
Date: Wed, 28 Oct 2009 22:32:00 GMT
x-kss-copy-source: /SourceBucket/SourceObjectKey
x-kss-tagging-directive:REPLACE
x-kss-tagging:TagA=A&TagB=B//需要URLencode
Authorization: authorization stringHTTP/1.1 200 OK
Date: Wed, 28 Oct 2009 22:32:00 GMT
Connection: keep-alive
x-kss-checksum-crc64ecma: 1408511733533619****
Server: KS3PUT /modifymetakey HTTP/1.1
Host: ks3-example.ks3-cn-beijing.ksyun.com
Date: Wed, 28 Oct 2009 22:32:00 GMT
x-kss-copy-source: /ks3-example/modifymetakey
x-kss-metadata-directive:REPLACE
x-kss-meta-youmetakey:yourmetavalue
Authorization: authorization stringHTTP/1.1 200 OK
Date: Wed, 28 Oct 2009 22:32:00 GMT
Connection: keep-alive
x-kss-checksum-crc64ecma: 1408511733533619****
Server: KS3
<CopyObjectResult>
<LastModified>2009-10-28T22:32:00</LastModified>
<ETag>"9b2cf535f27731c974343645a398****"</ETag>
<ChecksumCRC64ECMA>"9b2cf535f27731c974343645a398****"</ChecksumCRC64ECMA>
</CopyObjectResult>PUT /yourobjectkey HTTP/1.1
Host: yourbucket.ks3-cn-beijing.ksyuncs.com
Date: Wed, 28 Oct 2009 22:32:00 GMT
x-kss-copy-source: /yourbucket/yourobjectkey
x-kss-storage-class:STANDARD_IA
Authorization: authorization stringHTTP/1.1 200 OK
Date: Wed, 28 Oct 2009 22:32:00 GMT
Connection: keep-alive
x-kss-checksum-crc64ecma: 1408511733533619****
Server: KS3
<CopyObjectResult>
<LastModified>2009-10-28T22:32:00</LastModified>
<ETag>"9b2cf535f27731c974343645a398****"</ETag>
<ChecksumCRC64ECMA>"9b2cf535f27731c974343645a398****"</ChecksumCRC64ECMA>
</CopyObjectResult>当遇到网络断开或网络超时等异常情况，可能文件已经复制成功但客户未接收到成功响应，重试复制操作时由于已存在同名文件导致复制失败，该情况下建议先通过HEAD Object确认文件不存在后再进行重试复制操作。或者联系金山云售后服务人员，协助开通同名文件可选是否覆盖白名单，开通该白名单后，客户可通过请求中携带指定参数实现同名文件覆盖的复制操作。
错误码 | HTTP状态码 | 描述 |
|---|---|---|
ObjectAlreayExists | 400 | 要复制的目标存储中已经存在同名Key。 |
InvalidEncryptionAlgorithmError | 400 | x-kss-server-side-encryption请求头值不是AES256。 |
Md5NotMatchForOldMd5 | 400 | x-kss-copy-source-server-side-encryption-customer-key-MD5不是x-kss-copy-source-server-side-encryption-customer-key的MD5值。 |
AlgorithmInvalidForCustomerKey | 400 | x-kss-server-side-encryption-customer-algorithm不是合法的AES256。 |
纯净模式