You can call this operation to copy data from an existing object to upload a part by adding a x-oss-copy-request header to UploadPart.

Usage notes

To copy an object larger than 1 GB, use UploadPartCopy. For more information about how to copy objects smaller than 1 GB, see CopyObject.

When you use UploadPartCopy, take note of the following items:

  • You cannot call AppendObject to copy data from append objects.
  • When you call UploadPartCopy, the source and destination buckets must be located within the same region.
  • Before you call UploadPart to upload a part, you must call InitiateMultipartUpload to obtain an upload ID issued by the OSS server.
  • If the x-oss-server-side-encryption request header is specified when you call InitiateMultipartUpload, the uploaded part is encoded. The x-oss-server-side-encryption header is included in the response header of UploadPart, which indicates the server-side encryption method of the part. For more information, see InitiateMultipartUpload.
  • In the multipart upload mode, each part except the last part must be larger than 100 KB in size. The size of each part is not verified when you call UploadPart because not all parts are uploaded and the system does not know which part is the last part. The size of each part is verified only when you call CompleteMultipartUpload.

Versioning

By default, UploadPartCopy is used to upload a part by copying data from an existing object of the current version. To copy data from an object of a specific version, include versionId in the x-oss-copy-source request header as a subcondition in the request. You can set x-oss-copy-source to x-oss-copy-source : /SourceBucketName/SourceObjectName? versionId=111111.
Note The name of the source object must be URL-encoded. x-oss-copy-source-version-id is returned in the response, indicating the version ID of the source object.

If versionId is not specified and the current version of the source object is a delete marker, OSS returns 404 Not Found. If versionId is specified and the current version of the source object is a delete marker, OSS returns 400 Bad Request.

Request structure

PUT /ObjectName? partNumber=PartNumber&uploadId=UploadId HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Content-Length: Size
Authorization: SignatureValue
x-oss-copy-source: /SourceBucketName/SourceObjectName
x-oss-copy-source-range:bytes=first-last

Request headers

The following table describes the request headers in addition to commonly used request headers in the UploadPartCopy request.

Header Type Description
x-oss-copy-source String The address to access the source object. You must have permissions to read the source object.

Default value: null

x-oss-copy-source-range Integer The range of bytes to copy data from the source object. For example, if you specify bytes to 0 to 9, the system transfers byte 0 to byte 9, a total of 10 bytes.

Default value: null

  • If the x-oss-copy-source-range request header is not specified, the entire source object is copied.
  • If the x-oss-copy-source-range request header is specified, the response contains the length of the entire object and the range of bytes to be copied for this operation. For example, Content-Range: bytes 0~9/44 indicates that the length of the entire object is 44 bytes. The range of bytes to be copied is byte 0 to byte 9.
  • If the specified range does not conform to the range conventions, OSS copies the entire object and does not include Content-Range in the response.

The following table describes request headers that are used for x-oss-copy-source to specify the source object.

Header Type Description
x-oss-copy-source-if-match String The copy operation condition. If the ETag value of the source object is the same as the ETag value provided by the user, OSS copies data. Otherwise, OSS returns 412 Precondition Failed.

Default value: null

x-oss-copy-source-if-none-match String The object transfer condition. If the input ETag value does not match the ETag value of the object, the system transfers the object normally and returns 200 OK. Otherwise, OSS returns 304 Not Modified.

Default value: null

x-oss-copy-source-if-unmodified-since String The object transfer condition. If the specified time is the same as or later than the actual modified time of the object, OSS transfers the object normally and returns 200 OK. Otherwise, OSS returns 412 Precondition Failed.

Default value: null

x-oss-copy-source-if-modified-since String The object transfer condition. If the specified time is earlier than the actual modified time of the object, the system transfers the object normally and returns 200 OK. Otherwise, OSS returns 304 Not Modified.

Default value: null

Time format: ddd, dd MMM yyyy HH:mm:ss GMT. Example: Fri, 13 Nov 2015 14:47:53 GMT.

Examples

  • Sample requests
    PUT /multipart.data? partNumber=1&uploadId=0004B9895DBBB6EC98E36  HTTP/1.1
    Host: oss-example.oss-cn-hangzhou.aliyuncs.com
    Content-Length: 6291456
    Date: Wed, 22 Feb 2012 08:32:21 GMT
    Authorization: OSS qn6qrrqxo2oawuk53otf****:J/lICfXEvPmmSW86bBAfMmUm****
    x-oss-copy-source: /oss-example/ src-object
    x-oss-copy-source-range:bytes=100-6291756
    Sample responses
    HTTP/1.1 200 OK
    Server: AliyunOSS
    Connection: keep-alive
    x-oss-request-id: 3e6aba62-1eae-d246-6118-8ff42cd0****
    Date: Thu, 17 Jul 2014 06:27:54 GMT'
    <? xml version="1.0" encoding="UTF-8"? >
    <CopyPartResult xmlns=”http://doc.oss-cn-hangzhou.aliyuncs.com”>
        <LastModified>2014-07-17T06:27:54.000Z </LastModified>
        <ETag>"5B3C1A2E053D763E1B002CC607C5****"</ETag>
    </CopyPartResult>
  • Sample requests for specifying versionId for UploadPartCopy if a bucket has versioning enabled
    PUT /multipart.data? partNumber=2&uploadId=63C06A5CFF6F4AE4A6BB3AD7F01C****  HTTP/1.1
    Host: oss-example.oss-cn-hangzhou.aliyuncs.com
    Date: Tue, 09 Apr 2019 07:01:56 GMT
    Authorization: OSS 6jftttm6x6san0ewtgyk****:v/sJFtYvg7DTa4pJ2AMShZL/****
    x-oss-copy-source: /oss-example/src-object? versionId=CAEQMxiBgMC0vs6D0BYiIGJiZWRjOTRjNTg0NzQ1MTRiN2Y1OTYxMTdkYjQ0****
    Sample responses
    HTTP/1.1 200 OK
    Server: AliyunOSS
    Connection: keep-alive
    x-oss-copy-source-version-id: CAEQMxiBgMC0vs6D0BYiIGJiZWRjOTRjNTg0NzQ1MTRiN2Y1OTYxMTdkYjQ0****
    x-oss-request-id: 5CAC4364B7AEADE017000660
    Date: Tue, 09 Apr 2019 07:01:56 GMT
    <? xml version="1.0" encoding="UTF-8"? >
    <CopyPartResult>
      <LastModified>2019-04-09T07:01:56.000Z</LastModified>
      <ETag>"25A9F4ABFCC05743DF6E2C886C56****"</ETag>
    </CopyPartResult>

SDK

SDKs of the UploadPartCopy operation for various programming languages:

Error codes

Error code HTTP status code Description
OperationNotSupported 400 The error message returned because UploadPartCopy does not support the storage class of Archive.