DocsICP FilingConsole
官方文档
首页

UploadPartCopy

更新时间：
复制 MD 格式
产品详情
我的收藏

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

Usage notes

Use UploadPartCopy to copy files larger than 1 GB. For files smaller than 1 GB, use CopyObject.

When using UploadPartCopy:

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

  • Call InitiateMultipartUpload first to obtain an upload ID.

  • If you set the x-oss-server-side-encryption header in the InitiateMultipartUpload request, the uploaded part is encrypted. The UploadPart response returns this header with the encryption algorithm used. InitiateMultipartUpload.

  • All parts except the last must be larger than 100 KB. Part sizes are validated only when CompleteMultipartUpload is called.

Permissions

By default, an Alibaba Cloud account has full permissions. RAM users or RAM roles under an Alibaba Cloud account do not have any permissions by default. The Alibaba Cloud account or account administrator must grant operation permissions through RAM policies or Bucket Policy.

API

Action

Description

UploadPartCopy

oss:GetObject

Reads data in the source object when you upload a part by copying data from an existing object.

oss:PutObject

Writes data to the destination object when you upload a part by copying data from an existing object.

oss:GetObjectVersion

When uploading a part by copying data from an existing object, if you specify the object version through versionId, this permission is required to read the specified version of the source object.

Versioning

By default, UploadPartCopy copies from the current version of the source object. To copy a specific version, include the versionId sub-resource in x-oss-copy-source. Example: x-oss-copy-source : /SourceBucketName/SourceObjectName?versionId=111111.

Note

SourceObjectName must be URL-encoded. The response returns the versionId of the copied object in the x-oss-copy-source-version-id header.

If no versionId is specified and the current version is a delete marker, OSS returns 404 Not Found. If the specified versionId points to a delete marker, OSS returns 400 Bad Request.

Metering and billing

When you call UploadPartCopy, data retrieval fees apply if the source object uses Infrequent Access (IA) storage. If the source object uses Archive storage, has not been restored via RestoreObject, and real-time access of Archive objects is enabled for the bucket, data retrieval fees for real-time access of Archive objects apply. Fees are charged to the source bucket. Data processing fees.

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

当您在OSS ON云盒中调用该接口时，您需要将Host替换为云盒Endpoint。更多信息，请参见云盒Endpoint。

Request headers

In addition to common request headers, UploadPartCopy uses the following headers to specify the source object and copy range.

Name

Type

Description

x-oss-copy-source

String

The source object to copy. Read permission is required.

Default value: None

x-oss-copy-source-range

String

The byte range to copy from the source object. For example, bytes=0-9 copies the first 10 bytes.

Default value: None

  • If not specified, the entire source object is copied.

  • If specified, the response includes Content-Range with the total file length and copied range. Example: `Content-Range: bytes 0-9/44` indicates a 44-byte file with bytes 0–9 copied.

  • If the range is invalid, the entire object is copied and Content-Range is omitted.

The following headers apply to the source object specified in x-oss-copy-source.

Name

Type

Description

x-oss-copy-source-if-match

String

Copies the object only if its ETag matches the specified value. Otherwise, returns 412 Precondition Failed.

Default value: None

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

String

Copies the object only if its ETag differs from the specified value. Otherwise, returns 304 Not Modified.

Default value: None

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

String

Copies the object only if it has not been modified since the specified time. Otherwise, returns 412 Precondition Failed.

Default value: None

x-oss-copy-source-if-modified-since

String

Copies the object only if it has been modified since the specified time. Otherwise, returns 304 Not Modified.

Default value: None

Format: GMT. Example: Fri, 13 Nov 2015 14:47:53 GMT

Examples

  • Request example

    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: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
x-oss-copy-source: /oss-example/src-object
x-oss-copy-source-range: bytes=100-6291756

    Response example

    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>

  • Request example with a specified versionId

    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: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
x-oss-copy-source: /oss-example/src-object?versionId=CAEQMxiBgMC0vs6D0BYiIGJiZWRjOTRjNTg0NzQ1MTRiN2Y1OTYxMTdkYjQ0****

    Response example

    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 for this operation:

ossutil command line interface

The ossutil command for UploadPartCopy is upload-part-copy.

Error codes

Error code

HTTP status code

Description

OperationNotSupported

400

UploadPartCopy was called on a bucket that uses the Archive storage class.
Previous：UploadPartNext：CompleteMultipartUpload