tencent cloud

masukan

Copying and Moving Objects

Terakhir diperbarui:2022-01-17 16:45:47

    Overview

    This document provides an overview of APIs and SDK code samples related to object copy and movement.

    Simple operations

    API Operation Description
    PUT Object - Copy Copying an object (modifying object attributes) Copies a file to a destination path.

    Multipart operations

    API Operation Description
    Initiate Multipart Upload Copying a multipart upload Copies a multipart upload.
    Upload Part - Copy Copying an object part Copies a part of an object.
    Complete Multipart Upload Completing a multipart copy Completes the multipart copy of an object.

    Simple Operations

    Copying objects

    Description

    This API (PUT Object - Copy) is used to create a copy of an existing COS object, that is, to copy an object from the source path (object key) to the destination path (object key). During the process, object metadata and ACLs can be modified.
    You can use this API to create a copy of an object, modify an object’s metadata (the source object and destination file have the same attributes), and move or rename an object (copy the object first and then call the deletion API).

    Note:

    We recommend that you use this API to copy objects of 1-5 GB. For objects larger than 5 GB, please use the advanced API Slice Copy File.

    Sample code

    Copying an object:

    /* Copy a/1.jpg to b/1.jpg */
    cos.putObjectCopy({
       Bucket: 'examplebucket-1250000000', /* Your bucket name. Required. */
       Region: 'COS_REGION',  /* Bucket region, such as `ap-beijing`. Required. */
       Key: 'b/1.jpg',  /* Object key stored in the bucket (such as `1.jpg` and `a/b/test.txt`). Required. */
       CopySource: 'examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/a/1.jpg', /* Required */
    }, function(err, data) {
       console.log(err || data);
    });
    

    Parameter description

    Parameter Description Type Required
    Bucket Bucket name in the format of BucketName-APPID String Yes
    Region Bucket region. For the enumerated values, please see Regions and Access Endpoints. String Yes
    Key Object key (object name), the unique ID of an object in a bucket. For more information, please see Object Overview. String Yes
    CopySource URL of the source object. You can specify a previous version using the URL parameter ?versionId=<versionId>. String Yes
    ACL ACL attribute of the object. For the enumerated values, such as default, private, and public-read, please see the Preset ACL section in ACL Overview.
    Note: If you do not need access control for the object, set this parameter to default or do not specify it, in which case the object will inherit the permissions of its bucket.
    String No
    GrantRead Grants a user read access in the format: id="[OwnerUin]". You can use commas (,) to separate multiple users.
    • To authorize a sub-account, use id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>".
    • To authorize a root account, use id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>".
      Example: 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'
    String No
    GrantWrite Grants a user write access to the object’s ACL in the format: id="[OwnerUin]". You can use commas (,) to separate multiple users.
      • To authorize a sub-account, use id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>".
      • To authorize a root account, use id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>".
        Example: 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'
    String No
    GrantFullControl Grants a user full access in the format: id="[OwnerUin]". You can use commas (,) to separate multiple users.
    • To authorize a sub-account, use id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>".
    • To authorize a root account, use id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>".
      Example: 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'
    String No
    MetadataDirective Whether to copy the metadata. Enumerated values: Copy (default), Replaced. If it is set to Copy, the metadata of the source object will be copied and the user-defined metadata in the header will be ignored. If it is set to Replaced, the metadata of the source object will be replaced with the user-defined metadata in the header. If the destination and source paths are the same, that is, if you want to modify the metadata, this parameter must be set to Replaced. String No
    CopySourceIfModifiedSince Required modification time. The object is copied only if it has been modified after the specified time. Otherwise, 412 will be returned. This parameter can be used together with CopySourceIfNoneMatch. Using it together with other conditions may cause a conflict. String No
    CopySourceIfUnmodifiedSince Required unmodified time. The object is copied only if it hasn’t been modified since the specified time. Otherwise, 412 will be returned. This parameter can be used together with CopySourceIfMatch. Using it together with other conditions may cause a conflict. String No
    CopySourceIfMatch ETag that must be matched. The object is copied only if its ETag matches the specified value. Otherwise, 412 will be returned. This parameter can be used together with CopySourceIfUnmodifiedSince. Using it together with other conditions may cause a conflict. String No
    CopySourceIfNoneMatch ETag that cannot be matched. The object is copied only if its ETag does not match the specified value. Otherwise, 412 will be returned. This parameter can be used together with CopySourceIfModifiedSince. Using it together with other conditions may cause a conflict. string No
    StorageClass Storage class of the object. For the enumerated values, such as STANDARD (default), STANDARD_IA and ARCHIVE, please see Storage Class Overview. String No
    x-cos-meta-* Other user-defined file headers. String No

    Callback function description

    function(err, data) { ... }
    
    Parameter Description Type
    err Error code, which is returned when an error (network error or service error) occurs. If the request is successful, this parameter is empty. For more information, please see Error Codes. Object
    - statusCode HTTP status code, such as 200, 403, and 404 Number
    - headers Headers returned by the request Object
    data Content returned when the request is successful. If the request fails, this parameter is empty. Object
    - statusCode HTTP status code, such as 200, 403, and 404 Number
    - headers Headers returned by the request Object
    - ETag MD5 checksum of the object, such as "22ca88419e2ed4721c23807c678adbe4c08a7880". Note that double quotation marks are required at the beginning and the end. String
    - LastModified Last modified time of the object, for example, 2017-06-23T12:33:27.000Z String
    - VersionId Version ID of the uploaded object if versioning is enabled for its bucket. If versioning is not enabled, this parameter is not returned. String

    Moving an object

    Description

    Object movement involves copying the source object to the target location and deleting the source object.

    Since COS uses the bucket name (Bucket) and object key (ObjectKey) to identify objects, moving an object will change the object identifier. Currently, COS does not provide a standalone API to change object identifiers. However, you can still move the object with a combination of basic operations (object copy and object deletion).

    Sample code

    /* Move a/1.jpg to b/1.jpg */
    /* Alternatively, you can use the advanced copy API `cos.sliceCopyFile`. */
    cos.putObjectCopy({
       Bucket: 'examplebucket-1250000000', /* Your bucket name. Required. */
       Region: 'COS_REGION',  /* Bucket region, such as `ap-beijing`. Required. */
       Key: 'b/1.jpg',  /* Object key stored in the bucket (such as `1.jpg` and `a/b/test.txt`). Required. */
       CopySource: 'sourcebucket-1250000000.cos.ap-guangzhou.myqcloud.com/a/1.jpg', /* Required */
    }, function(err, data) {
       if (err) return console.log(err);
       /* Delete a/1.jpg */
       cos.deleteObject({
           Bucket: 'examplebucket-1250000000', /* Required */
           Region: 'COS_REGION',     /* Bucket region. Required */
           Key: 'a/1.jpg'        /* Required */
       }, function(err, data) {
           console.log(err || data);
       });
    });
    

    Modifying the storage class of an object

    Description

    To modify the storage class of an object, you can set StorageClass when copying the object (the source and destination objects are the same object).

    Sample code

    /* Set the storage class of 1.jpg in the root directory to ARCHIVE */
    /* Alternatively, you can use the advanced copy API `cos.sliceCopyFile`. */
    cos.putObjectCopy({
       Bucket: 'examplebucket-1250000000', /* Your bucket name. Required. */
       Region: 'COS_REGION',  /* Bucket region, such as `ap-beijing`. Required. */
       Key: '1.jpg',  /* Object key stored in the bucket (such as `1.jpg` and `a/b/test.txt`). Required. */
       CopySource: 'sourcebucket-1250000000.cos.ap-guangzhou.myqcloud.com/1.jpg', /* Required */
       StorageClass: 'ARCHIVE',  /* Set the storage class to ARCHIVE. */
    }, function(err, data) {
       console.log(err || data);
    });
    

    Multipart Operations

    Initializing a multipart copy

    Description

    This API (Initiate Multipart Uploads) is used to initialize a multipart copy. After a successful operation, an upload ID will be returned, which can be used in the subsequent Upload Part - Copy requests.

    Sample code

    cos.multipartInit({
       Bucket: 'examplebucket-1250000000', /* Your bucket name. Required. */
       Region: 'COS_REGION',  /* Bucket region, such as `ap-beijing`. Required. */
       Key: '1.jpg',  /* Object key stored in the bucket (such as `1.jpg` and `a/b/test.txt`). Required. */
    }, function(err, data) {
       console.log(err || data);
       if (data) {
         uploadId = data.UploadId;
       }
    });
    

    Parameter description

    Parameter Description Type Required
    Bucket Bucket name in the format of BucketName-APPID String Yes
    Region Bucket region. For the enumerated values, please see Regions and Access Endpoints. String Yes
    Key Object key (object name), the unique ID of an object in a bucket. For more information, please see Object Overview. String Yes
    CacheControl Cache policy as defined in RFC 2616. It will be stored as the object metadata. String No
    Content-Disposition Filename as defined in RFC 2616. It will be stored as the object metadata. String No
    ContentEncoding Encoding format as defined in RFC 2616. It will be stored as the object metadata. String No
    ContentType Content type (MIME) as defined in RFC 2616. It will be stored as the object metadata. String No
    Expires Expiration time as defined in RFC 2616. It will be stored as the object metadata. Expiration only invalidates the cache, and the file will not be deleted. String No
    ACL ACL attribute of the object. For the enumerated values, such as default, private, and public-read, please see the Preset ACL section in ACL Overview.
    Note: If you do not need access control for the object, set this parameter to default or do not specify it, in which case the object will inherit the permissions of its bucket.
    String No
    GrantRead Grants a user read permission for an object in the format: id="[OwnerUin]". You can use commas (,) to separate multiple users.
    • To authorize a sub-account, use id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>".
    • To authorize a root account, use id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>".
      Example: 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'
    String No
    GrantFullControl Grants a user full access in the format: id="[OwnerUin]". You can use commas (,) to separate multiple users.
    • To authorize a sub-account, use id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>".
    • To authorize a root account, use id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>".
      Example: 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'
    String No
    StorageClass Storage class of the object, such as STANDARD (default), STANDARD_IA, and ARCHIVE. For more information, please see Storage Class Overview. String No
    x-cos-meta-* User-defined headers, which will be returned as the object metadata. The maximum size is 2 KB. String No

    Callback function description

    function(err, data) { ... }
    
    Parameter Description Type
    err Error code, which is returned when an error (network error or service error) occurs. If the request is successful, this parameter is empty. For more information, please see Error Codes. Object
    data Content returned when the request is successful. If the request fails, this parameter is empty. Object
    Bucket Destination bucket for the multipart upload. Format: BucketName-APPID. Example: examplebucket-1250000000 String
    Key Object key (object name), the unique identifier of an object in a bucket. For more information, please see Object Overview. String
    UploadId Upload ID, which is required for the subsequent upload String

    Copying an object part

    Description

    This API (Upload Part - Copy) is used to copy a part of an object from the source path to the destination path.

    Note:

    To copy an object part, you must first initialize a multipart upload, after which a unique upload ID will be returned. This ID is required in the copy request.

    Sample code

    cos.uploadPartCopy({
       Bucket: 'examplebucket-1250000000', /* Your bucket name. Required. */
       Region: 'COS_REGION',  /* Bucket region, such as `ap-beijing`. Required. */
       Key: '1.jpg',  /* Object key stored in the bucket (such as `1.jpg` and `a/b/test.txt`). Required. */
       CopySource: 'sourcebucket-1250000000.cos.ap-guangzhou.myqcloud.com/sourceObject', /*Required*/
       UploadId: 'exampleUploadId', /*Required*/
       PartNumber: '1', /*Required*/
    }, function(err, data) {
       console.log(err || data);
       if (data) {
         eTag = data.ETag;
       }
    });
    

    Parameter description

    Parameter Description Type Required
    Bucket Bucket name in the format of BucketName-APPID String Yes
    Region Bucket region. For the enumerated values, please see Regions and Access Endpoints. String Yes
    Key Object key (object name), the unique ID of an object in a bucket. For more information, please see Object Overview. String Yes
    CopySource URL of the source object. You can specify a previous version using the URL parameter ?versionId=<versionId>. String Yes
    PartNumber Part number String Yes
    UploadId To upload an object in parts, you must first initialize the multipart upload. The response of the multipart upload initialization will carry a unique descriptor (an upload ID), which needs to be carried in the multipart upload request. String Yes
    CopySourceRange Byte range of the source object. The range value must be in the format of bytes=first-last, where both first and last are offsets starting from 0. For example, bytes=0-9 means to copy the first 10 bytes of the source object. If this parameter is not specified, the entire object will be copied. String No
    CopySourceIfMatch ETag that must be matched. The part will be copied only if its ETag matches the specified value. Otherwise, 412 will be returned. This parameter can be used together with x-cos-copy-source-If-Unmodified-Since. Using it together with other conditions may cause a conflict. String No
    CopySourceIfNoneMatch ETag that cannot be matched. The part is copied only if its ETag does not match the specified value. Otherwise, 412 will be returned. This parameter can be used together with x-cos-copy-source-If-Modified-Since. Using it together with other conditions may cause a conflict. string No
    CopySourceIfUnmodifiedSince Required unmodified time. The object is copied only if it hasn’t been modified since the specified time. Otherwise, 412 will be returned. This parameter can be used together with x-cos-copy-source-If-Match. Using it together with other conditions may cause a conflict. String No
    CopySourceIfModifiedSince Required modification time. The object is copied only if it has been modified after the specified time. Otherwise, 412 will be returned. This parameter can be used together with x-cos-copy-source-If-None-Match. Using it together with other conditions may cause a conflict. String No

    Callback function description

    function(err, data) { ... }
    
    Parameter Description Type
    err Error code, which is returned when an error (network error or service error) occurs. If the request is successful, this parameter is empty. For more information, please see Error Codes. Object
    - statusCode HTTP status code, such as 200, 403, and 404 Number
    - headers Headers returned by the request Object
    data Content returned when the request is successful. If the request fails, this parameter is empty. Object
    - statusCode HTTP status code, such as 200, 403, and 404 Number
    - headers Headers returned by the request Object
    - ETag MD5 checksum of the object, such as "22ca88419e2ed4721c23807c678adbe4c08a7880". Note that double quotation marks are required at the beginning and the end. String
    - LastModified Last modified time of the object, in GMT format String

    Completing a multipart copy

    Description

    This API (Complete Multipart Upload) is used to complete a multipart copy. After all parts are copied via the Copy Parts API, you need to call this API to complete the multipart copy. When using this API, you need to specify the PartNumber and ETag of each part in the request body for the part information to be verified.
    The parts need to be reassembled after they are copied, which takes several minutes. When the assembly starts, COS will immediately return the status code 200 and will periodically return spaces during the process to keep the connection active until the assembly is completed. After that, COS will return the assembled result in the body.

    • If the uploaded part size is below 1 MB, "400 EntityTooSmall" will be returned when this API is called.
    • If the uploaded part numbers are not continuous, "400 InvalidPart" will be returned when this API is called.
    • If the part information entries in the request body are not sorted by number in ascending order, "400 InvalidPartOrder" will be returned when this API is called.
    • If the UploadId does not exist, "404 NoSuchUpload" will be returned when this API is called.
    Note:

    We recommend you either complete or abort a multipart upload as early as possible, as the uploaded parts of an incomplete multipart upload will take up storage capacity and incur storage fees.

    Sample code

    cos.multipartComplete({
       Bucket: 'examplebucket-1250000000', /* Your bucket name. Required. */
       Region: 'COS_REGION',  /* Bucket region, such as `ap-beijing`. Required. */
       Key: '1.jpg',  /* Object key stored in the bucket (such as `1.jpg` and `a/b/test.txt`). Required. */
       UploadId: 'exampleUploadId', /* Obtained during the multipart task initialization. Required. */
       Parts: [
           {PartNumber: '1', ETag: 'exampleETag'},
       ]
    }, function(err, data) {
       console.log(err || data);
    });
    

    Parameter description

    Parameter Description Type Required
    Bucket Bucket name in the format of BucketName-APPID String Yes
    Region Bucket region. For the enumerated values, please see Regions and Access Endpoints. String Yes
    Key Object key (object name), the unique ID of an object in a bucket. For more information, please see Object Overview. String Yes
    UploadId ID of the upload String Yes
    Parts A list of information about the parts of the multipart upload ObjectArray Yes
    - PartNumber Part number String Yes
    - ETag MD5 checksum of each part.
    Example: "22ca88419e2ed4721c23807c678adbe4c08a7880"
    Note that double quotation marks are required at the beginning and the end.
    String Yes

    Callback function description

    function(err, data) { ... }
    
    Parameter Description Type
    err Error code, which is returned when an error (network error or service error) occurs. If the request is successful, this parameter is empty. For more information, please see Error Codes. Object
    - statusCode HTTP status code, such as 200, 403, and 404 Number
    - headers Headers Object
    data Content returned when the request is successful. If the request fails, this parameter is empty. Object
    - statusCode HTTP status code, such as 200, 403, and 404 Number
    - headers Headers Object
    - Location Public network access endpoint of the object String
    - Bucket Destination bucket for the multipart upload String
    - Key Object key (object name), the unique identifier of an object in a bucket. For more information, please see Object Overview. String
    - ETag Unique ID of the file after assembly in the format of "uuid-<part quantity="">".
    Example: "22ca88419e2ed4721c23807c678adbe4c08a7880-3". Note that double quotation marks are required at the beginning and the end.
    String

    Advanced APIs (Recommended)

    Advanced APIs are highly recommended. They encapsulate the native methods mentioned above to implement multipart copies.

    Copying an object in multiple parts

    Description

    This API (Slice Copy File) is used to copy an object from the source path to the destination path through multipart copy. During the copy, the object metadata and ACL can be modified. You can use this API to move, rename, and copy a file or modify its attributes.

    Method prototype

    Calling Slice Copy File

    /* Copy a/1.jpg to b/1.jpg */
    cos.sliceCopyFile({
       Bucket: 'examplebucket-1250000000', /* Your bucket name. Required. */
       Region: 'COS_REGION',  /* Bucket region, such as `ap-beijing`. Required. */
       Key: 'b/1.jpg',  /* Object key stored in the bucket (such as `1.jpg` and `a/b/test.txt`). Required. */
       CopySource: 'sourcebucket-1250000000.cos.ap-guangzhou.myqcloud.com/a/1.jpg', /* Required */
       onProgress:function (progressData) {                     /* Optional */
           console.log(JSON.stringify(progressData));
       }
    },function (err,data) {
       console.log(err || data);
    });
    

    Parameter description

    Parameter Description Type Required
    Bucket Bucket name in the format of BucketName-APPID String Yes
    Region Bucket region. For the enumerated values, please see Regions and Access Endpoints. String Yes
    Key Object key (object name), the unique ID of an object in a bucket. For more information, please see Object Overview. String Yes
    CopySource URL of the source object. You can specify a previous version using the URL parameter ?versionId=. String Yes
    ChunkSize Size (in bytes) of each part in the multipart copy. Defaults to 1048576 (1 MB). Number No
    SliceSize Specifies the minimum file size (in bytes) to use multipart copy. The default value is 5 GB. If the file size is equal to or smaller than this value, the file will be uploaded using putObjectCopy; otherwise, it will be uploaded using sliceCopyFile. Number No
    onProgress Callback for the upload progress, whose parameter is progressData Function No
    - progressData.loaded Size of the uploaded parts, in bytes Number No
    - progressData.total Size of the entire file, in bytes Number No
    - progressData.speed File upload speed, in bytes/s Number No
    - progressData.percent Percentage of the file upload progress, in decimal form. For example, 0.5 means 50% has been uploaded. Number No

    Callback function description

    function(err, data) { ... }
    
    Parameter Description Type
    err Error code, which is returned when an error (network error or service error) occurs. If the request is successful, this parameter is empty. For more information, please see Error Codes. Object
    - statusCode HTTP status code, such as 200, 403, and 404 Number
    - headers Headers Object
    data Content returned when the request is successful. If the request fails, this parameter is empty. Object
    - statusCode HTTP status code, such as 200, 403, and 404 Number
    - headers Headers Object
    - Location Public network access endpoint of the object String
    - Bucket Destination bucket for the multipart upload String
    - Key Object key (object name), the unique identifier of an object in a bucket. For more information, please see Object Overview. String
    - ETag MD5 checksum of the file after assembly.
    Example: "22ca88419e2ed4721c23807c678adbe4c08a7880". Note that double quotation marks are required at the beginning and the end.
    String
    - VersionId Version ID of the uploaded object if versioning is enabled for its bucket. If versioning is not enabled, this parameter is not returned. String
    Hubungi Kami

    Hubungi tim penjualan atau penasihat bisnis kami untuk membantu bisnis Anda.

    Dukungan Teknis

    Buka tiket jika Anda mencari bantuan lebih lanjut. Tiket kami tersedia 7x24.

    Dukungan Telepon 7x24