All Products
Search
Document Center

Object Storage Service:UploadPartCopy

Last Updated:Feb 26, 2024

Copies data from an existing object to upload a part by adding the x-oss-copy-source header to a UploadPart request.

Usage notes

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

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

  • Objects uploaded by calling AppendObject cannot be copied.

  • The source and destination buckets must be located in the same region.

  • Before you call UploadPartCopy to upload a part, you must call InitiateMultipartUpload to obtain an upload ID issued by the Object Storage Service (OSS) server.

  • If you specify the x-oss-server-side-encryption header when you call the InitiateMultipartUpload operation, the uploaded part is encrypted and the x-oss-server-side-encryption header is contained in the UploadPart response header. The value of the x-oss-server-side-encryption header indicates the server-side encryption algorithm of the part. For more information, see InitiateMultipartUpload.

  • In a multipart upload task, each part must be larger than 100 KB in size, except the last part. The size of each part is not verified when you call UploadPart because not all parts are uploaded and OSS 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 uploads a part by copying data from the current version of an object. To copy data from a specific version of an object, add versionId to the x-oss-copy-source request header as a subcondition in the request. You can set x-oss-copy-source in the following format: /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 a version ID is specified in the request and the specified version of the source object is a delete marker, OSS returns 400 Bad Request.

Request syntax

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 except for commonly used request headers in a 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.

By default, this header is left empty.

x-oss-copy-source-range

Integer

The range of bytes to copy from the source object. For example, if you set bytes to 0~9, OSS transfers a total of 10 bytes that range from byte 0 to byte 9.

By default, this header is left empty.

  • 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 that are copied for this operation. For example, Content-Range: bytes 0~9/44 indicates that the length of the entire object is 44 bytes and the range of bytes 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 the source object specified by x-oss-copy-source.

Header

Type

Description

x-oss-copy-source-if-match

String

The data copy condition. If the ETag value of the source object is the same as the specified ETag value, OSS copies data. Otherwise, OSS returns 412 Precondition Failed.

By default, this header is left empty.

x-oss-copy-source-if-none-match

String

The object transfer condition. If the specified ETag value does not match the ETag value of the source object, OSS transfers the object and returns 200 OK. Otherwise, OSS returns 304 Not Modified.

By default, this header is left empty.

x-oss-copy-source-if-unmodified-since

String

The object transfer condition. If the specified time is later than or equal to the actual modified time of the object, OSS transfers the object and returns 200 OK. Otherwise, OSS returns 412 Precondition Failed.

By default, this header is left empty.

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, OSS transfers the object as expected and returns 200 OK. Otherwise, OSS returns 304 Not Modified.

By default, this header is left empty.

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

Examples

  • Sample request

    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 response

    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 request 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 response

    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>

OSS SDKs

You can use OSS SDKs for the following programming languages to call UploadPartCopy:

Error codes

Error code

HTTP status code

Description

OperationNotSupported

400

UploadPartCopy cannot take effect on objects in Archive buckets.