All Products
Search
Document Center

Object Storage Service:upload-part-copy

Last Updated:Jul 03, 2025

Copies data from an existing object as a part and uploads the part.

Usage notes

  • To copy an object larger than 1 GB in size, run the upload-part-copy command. To copy an object smaller than 1 GB in size by running a single command, see copy-object.

  • When you run the upload-part-copy command, the source and destination buckets must be located within the same region.

  • Before you run the upload-part-copy command to upload a part, you must run the initiate-multipart-upload command to obtain an upload ID issued by the Object Storage Service (OSS) server.

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 Policy or Bucket Policy.

API

Action

Definition

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.

Syntax

ossutil api upload-part-copy --bucket value --key value --copy-source value --part-number value --upload-id value [flags]

Parameter

Type

Description

--bucket

string

The name of the bucket in which the source object is stored.

--key

string

The full path of the source object from which you want to copy data.

--copy-source

string

The address used to access the source object. format: bucket/UrIEncode(key). You must have the permissions to read the source object. The name of the source object must be URL-encoded.

--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.

--copy-source-if-modified-since

string

The object transfer condition. If the specified time is earlier than the last modified time of the source object, the system transfers the object and returns 200 OK. Otherwise, the system returns 304 Not Modified.

--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.

--copy-source-if-unmodified-since

string

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

--copy-source-range

string

The range of bytes that you want to copy from the source object.

--metadata-directive

string

The method that is used to configure the metadata of the destination object.

--part-number

string

The number that identifies a part.

--tagging

string

The tags of the destination object.

--tagging-directive

string

The method that is used to configure tags for the destination object.

--upload-id

string

The ID of the multipart upload task.

Note
  • The upload-part-copy command corresponds to the UploadPartCopy operation. For more information about the parameters in the UploadPartCopy operation, see UploadPartCopy.

  • For more information about supported global command-line options, see Global command-line options.

Examples

  • Copy data from the current version of srcobject in srcbucket as a part and upload the part.

    ossutil api upload-part-copy --bucket examplebucket --key exampleobject --copy-source /srcbucket/srcobject --upload-id 123 --part-number 1
  • Copy data from the current version of srcobject in srcbucket as a part in the JSON format and upload the part.

    ossutil api upload-part-copy --bucket examplebucket --key exampleobject --copy-source /srcbucket/srcobject --upload-id 123 --part-number 1 --output-format json
  • Copy data from the current version of srcobject in srcbucket as a part in the YAML format and upload the part.

    ossutil api upload-part-copy --bucket examplebucket --key exampleobject --copy-source /srcbucket/srcobject --upload-id 123 --part-number 1 --output-format json
  • Copy byte 0 to byte 9 from the current version of srcobject in srcbucket as a part and upload the part.

    ossutil api upload-part-copy --bucket examplebucket --key exampleobject --copy-source /srcbucket/srcobject --upload-id 123 --part-number 1 --copy-source-range bytes=0-9
  • Copy data from the current version of srcobject in srcbucket as a part and upload the part if the ETag of srcobject is 123.

    ossutil api upload-part-copy --bucket examplebucket --key exampleobject --copy-source /srcbucket/srcobject --upload-id 123 --part-number 1 --copy-source-if-match 123
  • Copy data from the current version of srcobject in srcbucket as a part and upload the part if the last modified time is earlier than Mon, 11 May 2020 08:16:23 GMT.

    ossutil api upload-part-copy --bucket examplebucket --key exampleobject --copy-source /srcbucket/srcobject --upload-id 123 --part-number 1 --copy-source-if-unmodified-since "Mon, 11 May 2020 08:16:23 GMT"
  • Copy data from the current version of srcobject in srcbucket as a part, upload the part, and use the tags specified in the request instead of the tags of the source object.

    ossutil api upload-part-copy --bucket examplebucket --key exampleobject --copy-source /srcbucket/srcobject --upload-id 123 --part-number 1 --tagging-directive Replace --tagging "TagA=A&TagB=B"