All Products
Search

This Product

    Object Storage Service:upload-part-copy

    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"