All Products
Search

This Product

    Object Storage Service:upload-part-copy

    Document Center

    Object Storage Service:upload-part-copy

    Last Updated:May 10, 2026

    This operation uploads a part by copying data from an existing object.

    Usage notes

    • To copy an object larger than 1 GB, you must use the upload-part-copy command. To copy an object smaller than 1 GB in a single operation, see copy-object.

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

    • Before uploading a part using this operation, you must first call the initiate-multipart-upload command to get an upload ID.

    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.

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

    --key

    string

    The full path of the destination object.

    --copy-source

    string

    The source address for the copy operation (you must have read permission for the source) is in the format bucket/UrIEncode(key), where the source object name must be URL encoded.

    --copy-source-if-match

    string

    Copies the part only if the ETag of the source object matches the specified ETag. Otherwise, a 412 Precondition Failed error is returned.

    --copy-source-if-modified-since

    string

    Copies the part only if the source object has been modified since the specified time. Otherwise, a 304 Not Modified error is returned.

    --copy-source-if-none-match

    string

    Copies the part only if the ETag of the source object does not match the specified ETag. Otherwise, a 304 Not Modified error is returned.

    --copy-source-if-unmodified-since

    string

    Copies the part only if the source object has not been modified since the specified time. Otherwise, a 412 Precondition Failed error is returned.

    --copy-source-range

    string

    The byte range of the source object to copy.

    --part-number

    string

    The part number, which must be unique for each part in the multipart upload.

    --upload-id

    string

    The upload ID for the multipart upload.

    Note

    • The upload-part-copy command wraps the UploadPartCopy API operation. For details about the API parameters, see the UploadPartCopy documentation.

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

    Examples

    • Upload a part by copying data from the current version of srcobject in the srcbucket bucket.

      ossutil api upload-part-copy --bucket examplebucket --key exampleobject --copy-source /srcbucket/srcobject --upload-id 123 --part-number 1

    • Upload a part by copying data and format the output as JSON.

      ossutil api upload-part-copy --bucket examplebucket --key exampleobject --copy-source /srcbucket/srcobject --upload-id 123 --part-number 1 --output-format json

    • Upload a part by copying data and format the output as YAML.

      ossutil api upload-part-copy --bucket examplebucket --key exampleobject --copy-source /srcbucket/srcobject --upload-id 123 --part-number 1 --output-format yaml

    • Upload a part by copying a specific range of bytes (0 to 9) from the source object.

      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

    • Upload a part by copying data only if the ETag of the source object srcobject matches 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

    • Upload a part by copying data only if the source object srcobject is unmodified since "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"