Object Operations

Last updated: 2020-06-12 15:04:47

    Overview

    This document provides an overview of APIs and SDK sample codes related to simple operations, multipart operations, and advanced APIs.

    Simple operations

    API Operation Description
    GET Bucket (List Objects) Querying an object list Queries some or all objects in a bucket
    GET Bucket Object Versions Querying a list objects and their version history Queries some or all objects in a bucket and their version history
    PUT Object Uploads an object using simple upload Uploads an object to a bucket
    HEAD Object Querying object metadata Queries the metadata of an object
    GET Object Downloading an object Downloads an object to the local file system
    PUT Object - Copy Copying an object Copies a file to a destination path
    DELETE Object Deleting a single object Deletes a specified object from a bucket
    DELETE Multiple Objects Deleting multiple objects Deletes multiple objects from a bucket in a single request
    POST Object restore Restoring an archived object Restores an archived object for access

    Multipart operations

    API Operation Description
    List Multipart Uploads Querying a multipart upload Queries the information of a multipart upload in progress
    Initiate Multipart Upload Initializing a multipart upload Initializes a multipart upload task
    Upload Part Uploading parts Uploads object parts
    Upload Part - Copy Copying a part Copies an object as a part
    List Parts Querying uploaded parts Queries the uploaded parts of a specified multipart upload operation
    Complete Multipart Upload Completing a multipart upload Completes the multipart upload of the entire object
    Abort Multipart Upload Aborting a multipart upload Aborts a multipart upload operation and deletes the uploaded parts

    Simple operations

    Querying an object list

    Feature description

    This API is used to query all the objects in a specified bucket.

    Method prototype

    public Guzzle\Service\Resource\Model listObjects(array $args = array());

    Sample request

    Sample 1. Querying a list of objects with the specified prefix and starting object
    try {
        $result = $cosClient->listObjects(array(
            'Bucket' => 'examplebucket-1250000000', //Format: BucketName-APPID
            'Delimiter' => '',
            'EncodingType' => 'url',
            'Marker' => 'doc/picture.jpg',
            'Prefix' => 'doc',
            'MaxKeys' => 1000,
        )); 
        // Request successful
        print_r($result);
    } catch (\Exception $e) {
        // Request failed
        echo($e);
    }

    Parameter description

    Parameter Name Type Description Required
    Bucket String Bucket name in the format: BucketName-APPID Yes
    Delimiter String A separator which is left empty by default. For example, you can specify it as / to indicate folders. No
    EncodingType String Indicates the encoding method of the returned value. The value is not encoded by default. Valid value: url No
    Marker String Marks the starting point of the returned object list. Entries are listed using UTF-8 binary order by default. No
    Prefix String Filters the object keys prefixed with the value of this parameter. It is left empty by default. No
    MaxKeys Int Maximum number of returned objects; the default value is 1,000. No

    Sample response

    Guzzle\Service\Resource\Model Object
    (
        [structure:protected] => 
        [data:protected] => Array
            (
                [Name] => examplebucket-1250000000
                [Prefix] => doc
                [Marker] => doc/picture.jpg
                [MaxKeys] => 10
                [IsTruncated] => 1
                [NextMarker] => doc/exampleobject
                [Contents] => Array
                    (
                        [0] => Array
                            (
                                [Key] => doc/exampleobject
                                [LastModified] => 2019-02-14T12:20:40.000Z
                                [ETag] => "e37b429559d82e852af0b2f5b4d078ab72b90208"
                                [Size] => 6532594
                                [Owner] => Array
                                    (
                                        [ID] => 100000000001
                                        [DisplayName] => 100000000001
                                    )
    
                                [StorageClass] => STANDARD
                            )
    
                        [1] => Array
                            (
                                [Key] => doc/exampleobject2
                                [LastModified] => 2019-03-04T06:34:43.000Z
                                [ETag] => "988f9f28e68eba9b8c1f5f98ccce0a3c"
                                [Size] => 28
                                [Owner] => Array
                                    (
                                        [ID] => 100000000001
                                        [DisplayName] => 100000000001
                                    )
    
                                [StorageClass] => STANDARD
                            )
                    )
                [RequestId] => NWNhMzM0MmZfOWUxYzBiMDlfOTk2YV83ZWE3ODE=
            )
    
    )

    Response description

    Parameter Name Type Description Parent Node
    Name String Bucket name in the format: BucketName-APPID None
    Delimiter String A separator which is left empty by default. For example, you can specify it as / to indicate folders. None
    EncodingType Specifies the encoding type of the returned value None
    Marker String Marks the starting point of the returned object list. Entries are listed using UTF-8 binary order by default. None
    Prefix String Filters the object keys prefixed with the value of this parameter. None
    MaxKeys Int Maximum number of returned objects; the default value is 1,000. None
    IsTruncated Int Indicates whether the returned objects are truncated None
    Contents Array Returned object list None
    Content Array Returned object attributes, contains a list of the metadata of all objects, including 'ETag', 'StorageClass', 'Key', 'Owner', 'LastModified', and 'Size' Contents

    Querying objects and their version history

    Feature description

    This API is used to query some or all objects in a bucket and their version history.

    Method prototype

    public Guzzle\Service\Resource\Model listObjectVersions(array $args = array());

    Sample request

    Sample 1. Querying a list of past object versions

    try {
        $result = $cosClient->listObjectVersions(array(
            'Bucket' => 'examplebucket-1250000000', //Format: BucketName-APPID
            'Delimiter' => '',
            'EncodingType' => 'url',
            'KeyMarker' => 'doc/picture.jpg',
            'VersionIdMarker' => 'MTg0NDUxODMyMTE2ODY0OTExOTk3W',
            'Prefix' => 'doc',
            'MaxKeys' => 1000,
        )); 
        print_r($result);
    } catch (\Exception $e) {
        echo($e);
    }

    Parameter description

    Parameter Name Type Description Required
    Bucket String Bucket name in the format: BucketName-APPID Yes
    Prefix String Filters the object keys prefixed with the value of this parameter. It is left empty by default. No
    Delimiter String A separator which is left empty by default. For example, you can specify it as / to indicate folders. No
    KeyMarker String Marks the starting key of the returned object list. Entries are listed in UTF-8 binary order by default. No
    VersionIdMarker String Marks the starting VersionId of the returned object list. Entries are listed in UTF-8 binary order by default. No
    MaxKeys Int Maximum number of returned objects; the default value is 1,000. No
    EncodingType String Indicates the encoding method of the returned value. The value is not encoded by default. Valid value: url No

    Sample response

    Guzzle\Service\Resource\Model Object
    (
        [structure:protected] => 
        [data:protected] => Array
            (
                [Name] => examplebucket-1250000000
                [Prefix] => doc
                [KeyMarker] => string
                [VersionIdMarker] => string
                [MaxKeys] => 10
                [IsTruncated] => 1
                [NextKeyMarker] => string
                [NextVersionIdMarker] => string
                [Versions] => Array
                    (
                        [0] => Array
                            (
                                [Key] => doc/exampleobject1
                                [VersionId] => null
                                [IsLatest] => 1
                                [LastModified] => 2019-06-13T09:24:52.000Z
                                [ETag] => "96e79218965eb72c92a549dd5a330112"
                                [Size] => 6
                                [StorageClass] => STANDARD
                                [Owner] => Array
                                    (
                                        [UID] => 1251668577
                                    )
                            )
    
                        [1] => Array
                            (
                                [Key] => doc/exampleobject2
                                [VersionId] => MTg0NDUxODMyMTE2ODY0OTExOTk
                                [IsLatest] => 1
                                [LastModified] => 2019-06-18T12:47:03.000Z
                                [ETag] => "698d51a19d8a121ce581499d7b701668"
                                [Size] => 3
                                [StorageClass] => STANDARD
                                [Owner] => Array
                                    (
                                        [UID] => 1251668577
                                    )
                            )
                        )
                [RequestId] => NWQwOGVkZGRfMjViMjU4NjRfODNjN18xMTE5YWI4
            )
    
    )

    Response description

    Parameter Name Type Description Parent Node
    Name String Bucket name in the format: BucketName-APPID None
    Delimiter String A separator which is left empty by default. For example, you can specify it as / to indicate folders. None
    EncodingType Specifies the encoding type of the returned value None
    KeyMarker String Marks the starting key of the returned object list. Entries are listed using UTF-8 binary order by default. None
    VersionIdMarker String Marks the starting VersionId of the returned object list. Entries are listed using UTF-8 binary order by default. None
    NextKeyMarker String Marks the starting key of the next list of returned objects if IsTruncated is true. None
    NextVersionIdMarker String Marks the starting VersionId of the next list of returned objects if IsTruncated is set to true. None
    Prefix String Filters the object keys prefixed with the value of this parameter. None
    MaxKeys Int Maximum number of returned objects; the default value is 1,000. None
    IsTruncated Int Indicates whether the returned objects are truncated None
    Versions Array An array of metadata on all the versions of each object None
    Version Array List of the metadata of objects with multiple versions, including 'ETag','StorageClass','Key','VersionId','IsLatest','Owner','LastModified',and 'Size' Versions
    CommonPrefixes Array All objects starting with a particular prefix and ending with the delimiter are grouped as a common prefix None

    Uploading an object using simple upload

    Feature description

    This API is used to upload an object to a specified bucket. You can upload objects up to 5 GB in size. Please use [Multipart Upload] (#.E5.88.86.E5.9D.97.E6.93.8D.E4.BD.9C) or [Advanced APIs] (#.E9.AB.98.E7.BA.A7.E6.8E.A5.E5.8F.A3.EF.BC.88.E6.8E.A8.E8.8D.90.EF.BC.89) to upload objects greater than 5 GB.

    Method prototype

    public Guzzle\Service\Resource\Model putObject(array $args = array())

    Sample request

    Sample 1. Uploading a local file

    try { 
        $result = $cosClient->putObject(array( 
            'Bucket' => 'examplebucket-1250000000', //Format: BucketName-APPID 
            'Key' => 'exampleobject', 
            'Body' => fopen('path/to/localFile', 'rb'), 
        )); 
        // Request successful 
        print_r($result);
    } catch (\Exception $e) { 
        // Request failed 
        echo($e); 
    }

    Sample 2. Uploading an archived file

    try { 
        $result = $cosClient->putObject(array( 
            'Bucket' => 'examplebucket-1250000000', //Format: BucketName-APPID 
            'Key' => 'exampleobject', 
            'Body' => fopen('path/to/localFile', 'rb'), 
            'StorageClass' => 'Archive'
        )); 
        // Request successful 
        print_r($result); 
    } catch (\Exception $e) { 
        // Request failed 
        echo($e); 
    }

    Sample 3. Uploading a file with a specified Content-type

    try { 
        $result = $cosClient->putObject(array( 
            'Bucket' => 'examplebucket-1250000000', //Format: BucketName-APPID 
            'Key' => 'exampleobject', 
            'Body' => fopen('path/to/localFile', 'rb'), 
            'ContentType' => 'text/xml'
        )); 
        // Request successful 
        print_r($result); 
    } catch (\Exception $e) { 
        // Request failed 
        echo($e); 
    }

    Parameter description

    Parameter Name Type Description Required
    Bucket String Bucket name in the format: BucketName-APPID Yes
    Key String ObjectKey is the unique identifier of an object in a bucket. For example, if the access domain name of an object is examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg,the object key is doc/pic.jpg No
    ACL String Sets the object ACL, e.g. 'private','public-read' No
    Body File/String Uploaded content Yes
    CacheControl String Cache policy. Sets Cache-Control. No
    ContentDisposition String File name. Sets Content-Disposition. No
    ContentEncoding String Encoding format. Sets Content-Encoding No
    ContentLanguage String Language type. Sets Content-Language No
    ContentLength Int Sets the length of the request content No
    ContentType String Content type. Sets Content-Type. No
    Expires String Sets Content-Expires. No
    Metadata Array User-defined file metadata No
    StorageClass String Sets the object storage class; enumerated values: STANDARD, STANDARD_IA, ARCHIVE. Default value: STANDARD No
    ContentMD5 String Sets the MD5 checksum of the uploaded file No
    ServerSideEncryption String Server-side encryption method No

    Sample response

    Guzzle\Service\Resource\Model Object
    (
        [structure:protected] => 
        [data:protected] => Array
            (
                [ETag] => "698d51a19d8a121ce581499d7b701668"
                [VersionId] => MTg0NDUxODMyMTE2ODY0OTExOTk
                [RequestId] => NWQwOGRkNDdfMjJiMjU4NjRfNzVjXzEwNmVjY2M=
                [ObjectURL] => http://lewzylucd2-1251668577.cos.ap-chengdu.myqcloud.com/123
            )
    
    )
    

    Response description

    Parameter Name Type Description Parent Node
    ETag String MD5 checksum of the uploaded file None
    VersionId String Version ID of the file if versioning is enabled. None

    Querying object metadata

    Feature description

    The API is used to query object metadata.

    Method prototype

    public Guzzle\Service\Resource\Model headObject(array $args = array());

    Sample request

    try {
        $result = $cosClient->headObject(array(
            'Bucket' => 'examplebucket-1250000000', //Format: BucketName-APPID
            'Key' => 'exampleobject',
        )); 
        // Request successful
        print_r($result);
    } catch (\Exception $e) {
        // Request failed
        echo($e);
    }

    Parameter description

    Parameter Name Type Description Required
    Bucket String Bucket name in the format: BucketName-APPID Yes
    Key String ObjectKey is the unique identifier of an object in a bucket. For example, if the access domain name of an object is examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg,the object key is doc/pic.jpg Yes
    VersionId String Version ID of the specified file if versioning is enabled. No

    Sample response

    Guzzle\Service\Resource\Model Object
    (
        [structure:protected] => 
        [data:protected] => Array
            (
                [DeleteMarker] => 
                [AcceptRanges] => 
                [Expiration] => 
                [Restore] => 
                [LastModified] => Tue, 02 Apr 2019 12:38:09 GMT
                [ContentLength] => 238186
                [ETag] => "af9f3b8eaf64473278909183abba1e31"
                [MissingMeta] => 
                [VersionId] => 
                [CacheControl] => 
                [ContentDisposition] => 
                [ContentEncoding] => 
                [ContentLanguage] => 
                [ContentType] => text/plain; charset=utf-8
                [Expires] => 
                [ServerSideEncryption] => 
                [Metadata] => Array
                    (
                        [md5] => af9f3b8eaf64473278909183abba1e31
                    )
                [SSECustomerAlgorithm] => 
                [SSECustomerKeyMD5] => 
                [SSEKMSKeyId] => 
                [StorageClass] => 
                [RequestCharged] => 
                [ReplicationStatus] => 
                [RequestId] => NWNhMzU3Y2ZfMzFhYzM1MGFfODdhMF8xOTExM2U=
            )
    
    )
    

    Response description

    Parameter Name Type Description Parent Node
    CacheControl String Cache policy. Sets Cache-Control. None
    ContentDisposition String File name. Sets Content-Disposition None
    ContentEncoding String Encoding format. Sets Content-Encoding None
    ContentLanguage String Language type. Sets Content-Language None
    ContentLength Int Sets the length of the request content None
    ContentType String Content type. Sets Content-Type. None
    Metadata Array User-defined file metadata None
    StorageClass String Sets the object storage class; enumerated values: STANDARD, STANDARD_IA, ARCHIVE None
    ServerSideEncryption String Server-side encryption method None
    ETag String MD5 checksum of the file None
    Restore String Restoration information of the archived file None

    Downloading an object

    Feature description

    This API is used to download an object.

    Method prototype

    public Guzzle\Service\Resource\Model getObject(array $args = array());
    

    Sample request

    Sample 1. Downloading a file
    try {
        $result = $cosClient->getObject(array(
            'Bucket' => 'examplebucket-1250000000', //Format: BucketName-APPID
            'Key' => 'exampleobject',
            'SaveAs' => 'path/to/localFile',
        )); 
        // Request successful
    } catch (\Exception $e) {
        // Request failed
        echo($e);
    }

    Sample 2. Getting file content within a certain byte range

    try {
        $result = $cosClient->getObject(array(
            'Bucket' => 'examplebucket-1250000000', //Format: BucketName-APPID
            'Key' => 'exampleobject',
            'Range' => 'bytes=0-10'
        )); 
        // Request successful
        print_r($result);
    } catch (\Exception $e) {
        // Request failed
        echo($e);
    }

    Sample 3. Downloading a file with a specified version ID

    try {
        $result = $cosClient->getObject(array(
            'Bucket' => 'examplebucket-1250000000', //Format: BucketName-APPID
            'Key' => 'exampleobject',
            'VersionId' => 'exampleVersionId'
        )); 
        // Request successful
        print_r($result);
    } catch (\Exception $e) {
        // Request failed
        echo($e);
    }

    Parameter description

    Parameter Name Type Description Required
    Bucket String Bucket name in the format: BucketName-APPID Yes
    Key String ObjectKey is the unique identifier of an object in a bucket. For example, if the access domain name of an object is examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg,the object key is doc/pic.jpg Yes
    SaveAs String Local path for saving the file No
    VersionId String Version ID of the specified file if versioning is enabled No
    Range String Sets the byte range of the file to be downloaded in the format: bytes=first-last No
    ResponseCacheControl String Sets the Cache-Control in the response header No
    ResponseContentDisposition String Sets the Content-Disposition in the response header No
    ResponseContentEncoding String Sets the Content-Encoding in the response header No
    ResponseContentLanguage String Sets the Content-Language in the response header No
    ResponseContentType String Sets the Content-Type in the response header No
    ResponseExpires String Sets the Content-Expires in the response header No

    Sample response

    Guzzle\Service\Resource\Model Object
    (
        [structure:protected] => 
        [data:protected] => Array
            (
                [Body] => 
                [DeleteMarker] => 
                [AcceptRanges] => bytes
                [Expiration] => 
                [Restore] => 
                [LastModified] => Tue, 02 Apr 2019 20:38:09 GMT
                [ContentLength] => 238186
                [ETag] => "af9f3b8eaf64473278909183abba1e31"
                [MissingMeta] => 
                [VersionId] => 
                [CacheControl] => 
                [ContentDisposition] => 
                [ContentEncoding] => 
                [ContentLanguage] => 
                [ContentRange] => 
                [ContentType] => text/plain; charset=utf-8
                [Expires] => 
                [WebsiteRedirectLocation] => 
                [ServerSideEncryption] => 
                [Metadata] => Array
                    (
                        [md5] => af9f3b8eaf64473278909183abba1e31
                    )
    
                [SSECustomerAlgorithm] => 
                [SSECustomerKeyMD5] => 
                [SSEKMSKeyId] => 
                [StorageClass] => 
                [RequestCharged] => 
                [ReplicationStatus] => 
                [RequestId] => NWNhNDBmYzBfNmNhYjM1MGFfMmUzYzFfMWIzMDYz
            )
    
    )
    

    Response description

    Parameter Name Type Description Parent Node
    Body File/String Downloaded content None
    ETag String MD5 checksum of the file None
    Expires String Content-Expires None
    Metadata Array User-defined file metadata None
    StorageClass String Sets the object storage class; enumerated values: STANDARD, STANDARD_IA, ARCHIVE. Default value: STANDARD None
    ContentMD5 String Sets the MD5 checksum of the uploaded file None
    ServerSideEncryption String Server-side encryption method None
    CacheControl String Cache policy. Sets Cache-Control. None
    ContentDisposition String File name. Sets Content-Disposition None
    ContentEncoding String Encoding format. Sets Content-Encoding None
    ContentLanguage String Language type. Sets Content-Language None
    ContentLength Int Sets the length of the request content None
    ContentType String Content type. Sets Content-Type. None
    Metadata Array User-defined file metadata None
    Restore String Restoration information of the archived file None

    Setting object replication

    This API is used to copy an object to the destination path.

    Method prototype

    public Guzzle\Service\Resource\Model copyObject(array $args = array());
    

    Sample request

    Sample 1. Copying an object

    try {
        $result = $cosClient->copyObject(array(
            'Bucket' => 'examplebucket-1250000000', //Format: BucketName-APPID
            'Key' => 'exampleobject',
            'CopySource' => 'sourcebucket-1250000000.cos.ap-guangzhou.myqcloud.com/sourceObject',
        )); 
        // Request successful
        print_r($result);
    } catch (\Exception $e) {
        // Request failed
        echo($e);
    }

    Sample 2. Copying an object with specified version ID

    try {
        $result = $cosClient->copyObject(array(
            'Bucket' => 'examplebucket-1250000000', //Format: BucketName-APPID
            'Key' => 'exampleobject',
            'CopySource' => 'sourcebucket-1250000000.cos.ap-guangzhou.myqcloud.com/sourceObject?versionId=MTg0NDUxNjI3NTM0ODE2Njc0MzU',
        )); 
        // Request successful
        print_r($result);
    } catch (\Exception $e) {
        // Request failed
        echo($e);
    }

    Sample 3. Changing the storage class to ARCHIVE

    try {
        $result = $cosClient->copyObject(array(
            'Bucket' => 'examplebucket-1250000000', //Format: BucketName-APPID
            'Key' => 'exampleobject',
            'CopySource' => 'sourcebucket-1250000000.cos.ap-guangzhou.myqcloud.com/sourceObject',
            'StorageClass' => 'Archive'
        )); 
        // Request successful
        print_r($result);
    } catch (\Exception $e) {
        // Request failed
        echo($e);
    }

    Sample 4. Modifying metadata

    try {
        $result = $cosClient->copyObject(array(
            'Bucket' => 'examplebucket-1250000000', //Format: BucketName-APPID
            'Key' => 'exampleobject',
            'CopySource' => 'sourcebucket-1250000000.cos.ap-guangzhou.myqcloud.com/sourceObject',
            'MetadataDirective' => 'Replaced',
            'Metadata' => array(
                'key1' => 'value1',
                'key2' => 'value2',
            )
        )); 
        // Request successful
        print_r($result);
    } catch (\Exception $e) {
        // Request failed
        echo($e);
    }

    Parameter description

    Parameter Name Type Description Required
    Bucket String Bucket name in the format: BucketName-APPID Yes
    Key String ObjectKey is the unique identifier of an object in a bucket. For example, if the access domain name of an object is examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg,the object key is doc/pic.jpg Yes
    CopySource String Describes the path to the source object, including Appid, Bucket, Key, and Region,
    for example, examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg
    Yes
    MetadataDirective String Valid values: 'Copy': ignore the configured metadata and copy the file directly; 'Replaced': modify the metadata according to the configured metadata. If the destination path is identical to the source path, this parameter must be set to ‘Replaced’. No

    Deleting a single object

    Feature description

    This API is used to delete a specified object (file/object) from a bucket.

    Method prototype

    public Guzzle\Service\Resource\Model deleteObject(array $args = array());
    

    Sample request

    try {
        $result = $cosClient->deleteObject(array(
            'Bucket' => 'examplebucket-1250000000', //Format: BucketName-APPID
            'Key' => 'exampleobject',
            'VersionId' => 'exampleVersionId'
        )); 
        // Request successful
        print_r($result);
    } catch (\Exception $e) {
        // Request failed
        echo($e);
    }

    Parameter description

    Parameter Name Type Description Required
    Bucket String Bucket name in the format: BucketName-APPID Yes
    Key String ObjectKey is the unique identifier of an object in a bucket. For example, if the access domain name of an object is examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg,the object key is doc/pic.jpg Yes
    VersionId String Version ID of the deleted file No

    Deleting multiple objects

    Feature description

    This API is used delete multiple objects from a specified bucket in a single request.

    Method prototype

    public Guzzle\Service\Resource\Model deleteObjects(array $args = array());
    

    Sample request

    try {
        $result = $cosClient->deleteObjects(array(
            'Bucket' => 'examplebucket-1250000000', //Format: BucketName-APPID
            'Objects' => array(
                array(
                    'Key' => 'exampleobject',
                    'VersionId' => 'string'
                ),  
                // ... repeated
            ),  
        )); 
        // Request successful
        print_r($result);
    } catch (\Exception $e) {
        // Request failed
        echo($e);
    }

    Parameter description

    Parameter Name Type Description Required
    Bucket String Bucket name in the format: BucketName-APPID Yes
    Objects Array List of deleted objects Yes
    Object Array Deleted object Yes
    Key String ObjectKey is the unique identifier of an object in a bucket. For example, if the access domain name of an object is examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg,the object key is doc/pic.jpg Yes
    VersionId String Version ID of the deleted file No

    Sample response

    Guzzle\Service\Resource\Model Object
    (
        [structure:protected] => 
        [data:protected] => Array
            (
                [Deleted] => Array
                    (
                        [0] => Array
                            (
                                [Key] => exampleobject1
                            )
                    )
                [Errors] => Array
                    (
                        [0] => Array
                            (
                                [Key] => exampleobject2
                                [Code] => 
                                [Message] => 
                            )
                    )
                [RequestId] => NWNhZWYzYWNfMTlhYTk0MGFfNGRjX2MzZTVhOQ==
            )
    )
    

    Response description

    Parameter Name Type Description Parent Node
    Deleted Array List of successfully deleted objects None
    Errors Array List of objects that failed to be deleted None
    Key String Object key Deleted/Errors
    Code String Error code for failed operations Errors
    Message String Error message for failed operations Errors

    Restoring an archived object

    Feature description

    This API is used to retrieve an archived object for access.

    Method prototype

    public Guzzle\Service\Resource\Model restoreObject(array $args = array());

    Sample request

    try {
        $result = $cosClient->restoreObject(array(
            'Bucket' => 'examplebucket-1250000000', //Format: BucketName-APPID
            'Key' => 'exampleobject',
            'Days' => 10,
            'CASJobParameters' => array(
                'Tier' =>'Expedited'
            )    
        )); 
        // Request successful
        print_r($result);
    } catch (\Exception $e) {
        // Request failed
        echo($e);
    }

    Parameter description

    Parameter Name Type Description Required
    Bucket String Bucket name in the format: BucketName-APPID Yes
    Key String Object key Yes
    Days String Sets the number of days before the temporary copy expires Yes
    CASJobParameters Array Restoration information Yes
    Tier String When restoring data, you can use Tier to specify one of the three restoration types supported by CAS: Expedited, Standard, and Bulk. Yes

    Multipart operations

    Operations related to multipart uploads include the following:

    • Uploading objects with multipart upload: initializing a multipart upload, uploading parts, and completing a multipart upload.
    • Resuming a multipart upload: querying uploaded parts, uploading remaining parts, and completing a multipart upload.
    • Deleting uploaded parts.

    Querying a multipart upload

    Feature description

    This API is used to query in-progress multipart uploads in a specified bucket.

    Method prototype

    public Guzzle\Service\Resource\Model listMultipartUploads(array $args = array());
    

    Sample request

    try {
        $result = $cosClient->listMultipartUploads(array(
            'Bucket' => 'examplebucket-1250000000', //Format: BucketName-APPID
            'Delimiter' => '/',
            'EncodingType' => 'url',
            'KeyMarker' => 'prfixKeyMarker',
            'UploadIdMarker' => 'string',
            'Prefix' => 'prfix',
            'MaxUploads' => 1000,
        )); 
        // Request successful
        print_r($result);
    } catch (\Exception $e) {
        // Request failed
        echo($e);
    }

    Parameter description

    Parameter Name Type Description Required
    Bucket String Bucket name in the format: BucketName-APPID Yes
    Delimiter String A separator which is left empty by default. For example, you can specify it as / to indicate folders. No
    EncodingType String Indicates the encoding method of the returned value. The value is not encoded by default. Valid value: url No
    KeyMarker String Marks the starting key of the list of returned parts No
    UploadIdMarker String Marks the starting upload ID of the list of returned parts No
    Prefix String Filters the object keys prefixed with the value of this parameter. It is left empty by default. No
    MaxUploads Int The maximum number of returned parts; the default value is 1,000. No

    Sample response

    Guzzle\Service\Resource\Model Object
    (
        [structure:protected] => 
        [data:protected] => Array
            (
                [Bucket] => examplebucket-1250000000
                [EncodingType] => 
                [KeyMarker] => 
                [UploadIdMarker] => 
                [MaxUploads] => 1000
                [Prefix] => 
                [IsTruncated] => 
                [Uploads] => Array
                    (
                        [0] => Array
                            (
                                [Key] => exampleobject
                                [UploadId] => 1551693693b1e6d0e00eec30c534059865ec89c9393028b60bfaf167e9420524b25eeb2940
                                [Initiator] => Array
                                    (
                                        [ID] => qcs::cam::uin/100000000001:uin/100000000001
                                        [DisplayName] => 100000000001
                                    )
    
                                [Owner] => Array
                                    (
                                        [ID] => qcs::cam::uin/100000000001:uin/100000000001
                                        [DisplayName] => 100000000001
                                    )
    
                                [StorageClass] => STANDARD
                                [Initiated] => 2019-03-04T10:01:33.000Z
                            )
    
                        [1] => Array
                            (
                                [Key] => exampleobject
                                [UploadId] => 155374001100563fe0e9d37964d53077e54e9d392bce78f630359cd3288e62acee2b719534
                                [Initiator] => Array
                                    (
                                        [ID] => qcs::cam::uin/100000000001:uin/100000000001
                                        [DisplayName] => 100000000001
                                    )
    
                                [Owner] => Array
                                    (
                                        [ID] => qcs::cam::uin/100000000001:uin/100000000001
                                        [DisplayName] => 100000000001
                                    )
    
                                [StorageClass] => STANDARD
                                [Initiated] => 2019-03-28T02:26:51.000Z
                            )
    
                    )
    
                [RequestId] => NWNhNDJmNzBfZWFhZDM1MGFfMjYyM2FfMWIyNzhh
            )
    
    )

    Response description

    Parameter Name Type Description Parent Node
    Bucket String Bucket name in the format: BucketName-APPID None
    IsTruncated Int Indicates whether the returned objects are truncated None
    Uploads Array List of returned parts None
    Upload Array Attributes of the returned parts Uploads
    Key String Object key Upload
    UploadId String ID of the multipart upload Upload
    Initiator String Initiator of the multipart upload Upload
    Owner String Owner of the multipart upload Upload
    StorageClass String Storage class of the multipart upload Upload
    Initiated String Time the multipart upload was initiated Upload

    Initializing-multipart-upload-">

    Initializing multipart upload

    Feature description

    This API is used to initialize a multipart upload.

    Method prototype

    public Guzzle\Service\Resource\Model createMultipartUpload(array $args = array());
    

    Sample request

    try {
        $result = $cosClient->createMultipartUpload(array(
            'Bucket' => 'examplebucket-1250000000', //Format: BucketName-APPID
            'Key' => 'exampleobject',
        )); 
        // Request successful
        print_r($result);
    } catch (\Exception $e) {
        // Request failed
        echo($e);
    }

    Parameter description

    Parameter Name Type Description Required
    Bucket String Bucket name in the format: BucketName-APPID Yes
    Key String ObjectKey is the unique identifier of an object in a bucket. For example, if the access domain name of an object is examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg,the object key is doc/pic.jpg Yes
    CacheControl String Cache policy. Sets Cache-Control. No
    ContentDisposition String File name. Sets Content-Disposition. No
    ContentEncoding String Encoding format. Sets Content-Encoding No
    ContentLanguage String Language type. Sets Content-Language No
    ContentLength Int Sets the length of the request content No
    ContentType String Content type. Sets Content-Type. No
    Expires String Sets Content-Expires. No
    Metadata Array User-defined file metadata No
    StorageClass String Sets the object storage class; enumerated values: STANDARD, STANDARD_IA, ARCHIVE. Default value: STANDARD No
    ContentMD5 String Sets the MD5 checksum of the uploaded file No
    ServerSideEncryption String Server-side encryption method No

    Sample response

    Guzzle\Service\Resource\Model Object
    (
        [structure:protected] => 
        [data:protected] => Array
            (
                [Bucket] => examplebucket-1250000000
                [Key] => exampleobject
                [UploadId] => 1554277569b3e83df05c730104c325eb7b56000449fb7d51300b0728aacde02a6ea7f6c033
                [RequestId] => NWNhNDY0YzFfMmZiNTM1MGFfNTM2YV8xYjliMTg=
            )
    
    )

    Response description

    Parameter Name Type Description Parent Node
    Bucket String Bucket name in the format: BucketName-APPID None
    Key String Object key None
    UploadId String ID of the multipart upload None

    -Uploading-parts">

    Uploading parts

    This API is used to upload parts.

    Method prototype

    public Guzzle\Service\Resource\Model uploadPart(array $args = array());
    

    Sample request

    try {
        $result = $cosClient->uploadPart(array(
            'Bucket' => 'examplebucket-1250000000', //Format: BucketName-APPID
            'Key' => 'exampleobject', 
            'Body' => 'string',
            'UploadId' => 'exampleUploadId', // UploadId is the ID of the multipart upload, which you can get in the response of the initialization of the multipart upload 
            'PartNumber' => 1, // Part number; COS will merge parts based on part number
        )); 
        // Request successful
        print_r($result);
    } catch (\Exception $e) {
        // Request failed
        echo($e);
    }

    Parameter description

    Parameter Name Type Description Required
    Bucket String Bucket name in the format: BucketName-APPID Yes
    Key String Object key Yes
    UploadId String ID of the multipart upload. This value is returned in the response of the initialization of the multipart Upload Yes
    Body File/String Uploaded content Yes
    PartNumber Int Part number; COS will merge parts based on part number Yes
    ContentLength Int Sets the length of the request content No
    ContentMD5 String Sets the MD5 checksum of the uploaded file No

    Sample response

    Guzzle\Service\Resource\Model Object
    (
        [structure:protected] => 
        [data:protected] => Array
            (
                [ETag] => "96e79218965eb72c92a549dd5a330112"
                [RequestId] => NWNhNDdjYWFfNjNhYjM1MGFfMjk2NF8xY2ViMWM=
            )
    
    )

    Response description

    Parameter Name Type Description Parent Node
    ETag String MD5 checksum of the part None

    Copying parts

    Feature description

    This API is used to copy an object as a part.

    Method prototype

    public Guzzle\Service\Resource\Model uploadPartCopy(array $args = array());
    

    Sample request

    try {
        $result = $cosClient->uploadPartCopy(array(
            'Bucket' => 'examplebucket-1250000000', //Format: BucketName-APPID
            'Key' => 'exampleobject', 
            'CopySource' => 'sourcebucket-1250000000.cos.ap-guangzhou.myqcloud.com/sourceObject',
            'CopySourceRange' => 'bytes=0-1', // For example, copy only the first 2 bytes.
            'UploadId' => 'exampleUploadId', // UploadId is the ID of the multipart upload, which you can get in the response of the initialization of the multipart upload 
            'PartNumber' => 1, // Part number; COS will merge parts based on part number
        )); 
        // Request successful
        print_r($result);
    } catch (\Exception $e) {
        // Request failed
        echo($e);
    }

    Parameter description

    Parameter Name Type Description Required
    Bucket String Bucket name in the format: BucketName-APPID Yes
    Key String Object key Yes
    UploadId String ID of the multipart upload. This value is returned in the response of the initialization of the multipart Upload Yes
    CopySource String Describes the path to the source object, including Appid, Bucket, Key, and Region,
    for example, examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg
    Yes
    CopySource String Describes the byte range of the source object to be copied in the format: bytes=first-last. The entire source object will be copied by default if no range is specified. No
    PartNumber Int Part number; COS will merge parts based on part number Yes
    ContentLength Int Sets the length of the request content No
    ContentMD5 String Sets the MD5 checksum of the uploaded file No

    Sample response

    Guzzle\Service\Resource\Model Object
    (
        [structure:protected] => 
        [data:protected] => Array
            (
                [ETag] => "96e79218965eb72c92a549dd5a330112"
                [LastModified] => "2017-09-04T04:45:45"
                [RequestId] => NWNhNDdjYWFfNjNhYjM1MGFfMjk2NF8xY2ViMWM=
            )
    
    )

    Response description

    Parameter Name Type Description Parent Node
    ETag String MD5 checksum of the part None
    LastModified String Returns the date/time the object was last modified in GMT format None

    -Querying-uploaded-parts-">

    Querying uploaded parts

    Feature description

    This API is used to query the uploaded parts of a specific multipart upload operation.

    Method prototype

    public Guzzle\Service\Resource\Model listParts(array $args = array());

    Sample request

    try {
        $result = $cosClient->listParts(array(
            'Bucket' => 'examplebucket-1250000000', //Format: BucketName-APPID
            'Key' => 'exampleobject',
            'UploadId' => 'exampleUploadId',
            'PartNumberMarker' => 1,
            'MaxParts' => 1000,
        )); 
        // Request successful
        print_r($result);
    } catch (\Exception $e) {
        // Request failed
        echo($e);
    }

    Parameter description

    Parameter Name Type Description Required
    Bucket String Bucket name in the format: BucketName-APPID Yes
    Key String Object key Yes
    UploadId String ID of the multipart upload Yes
    PartNumberMarker Int Marks the starting part of the list of returned parts No
    MaxParts Int The maximum number of returned parts; the default value is 1,000. No

    Sample response

    Guzzle\Service\Resource\Model Object
    (
        [structure:protected] => 
        [data:protected] => Array
            (
                [Bucket] => examplebucket-1250000000
                [Key] => exampleobject
                [UploadId] => 1554279643cf19d71bb5fb0d29613e5541131f3a96387d9e168cd939c23a3d608c9eb94707
                [Owner] => Array
                    (
                        [ID] => 1250000000
                        [DisplayName] => 1250000000
                    )
                [PartNumberMarker] => 1
                [Initiator] => Array
                    (
                        [ID] => qcs::cam::uin/100000000001:uin/100000000001
                        [DisplayName] => 100000000001
                    )
                [StorageClass] => Standard
                [MaxParts] => 1000
                [IsTruncated] => 
                [Parts] => Array
                    (
                        [0] => Array
                            (
                                [PartNumber] => 2
                                [LastModified] => 2019-04-03T08:21:28.000Z
                                [ETag] => "b948e77469189ac94b98e09755a6dba9"
                                [Size] => 1048576
                            )
                        [1] => Array
                            (
                                [PartNumber] => 3
                                [LastModified] => 2019-04-03T08:21:22.000Z
                                [ETag] => "9e5060e2994ec8463bfbebd442fdff16"
                                [Size] => 1048576
                            )                       
                    )
                [RequestId] => NWNhNDZkNTJfOGNiMjM1MGFfMTRlYl8xYmJiOTU=
            )
    
    )
    

    Response description

    Parameter Name Type Description Parent Node
    Bucket String Bucket name in the format: BucketName-APPID None
    Key String Object key None
    UploadId String ID of the multipart upload None
    IsTruncated Int Indicates whether the returned objects are truncated None
    PartNumberMarker Int Marks the starting part of the list of returned parts None
    MaxParts Int The maximum number of returned parts; the default value is 1,000. None
    Initiator String Initiator of the multipart upload None
    Parts Array List of returned parts None
    Part Array Attributes of the returned parts Parts
    PartNumber Int Part number which serves to identify the part Part
    LastModified String Date/time the part was last modified/time Part
    ETag String MD5 checksum of the part Part
    Size String Size of the part Part

    -Completing-a-multipart-upload-</-span>">

    Completing a multipart upload </ span>

    Feature description

    This API is used to complete the multipart upload of the entire file.

    Method prototype

    public Guzzle\Service\Resource\Model completeMultipartUpload(array $args = array());
    

    Sample request

    try {
        $result = $cosClient->completeMultipartUpload(array(
            'Bucket' => 'examplebucket-1250000000', //Format: BucketName-APPID
            'Key' => 'exampleobject', 
            'UploadId' => 'exampleUploadId',
            'Parts' => array(
                array(
                    'ETag' => 'exampleETag',
                    'PartNumber' => 1,
                )), 
                // ... repeated
        )); 
        // Request successful
        print_r($result);
    } catch (\Exception $e) {
        // Request failed
        echo($e);
    }

    Parameter description

    Parameter Name Type Description Required
    Bucket String Bucket name in the format: BucketName-APPID Yes
    Key String Object key Yes
    UploadId String ID of the multipart upload Yes
    Parts Array List of parts Yes
    Part Array Information on the uploaded parts Yes
    ETag String MD5 checksum of the part Yes
    PartNumber Int Part number which serves to identify the part Yes

    -Aborting-a-multipart-upload-">

    Aborting a multipart upload

    Feature description

    This API is used to abort a multipart upload and delete the uploaded parts.

    Method prototype

    public Guzzle\Service\Resource\Model abortMultipartUpload(array $args = array());

    Sample request

    try {
        $result = $cosClient->abortMultipartUpload(array(
            'Bucket' => 'examplebucket-1250000000', //Format: BucketName-APPID
            'Key' => 'exampleobject', 
            'UploadId' => 'exampleUploadId',
        )); 
        // Request successful
        print_r($result);
    } catch (\Exception $e) {
        // Request failed
        echo($e);
    }

    Parameter description

    Parameter Name Type Description Required
    Bucket String Bucket name in the format: BucketName-APPID Yes
    Key String Object key Yes
    UploadId String ID of the multipart upload Yes

    Advanced APIs (recommended)

    This section encapsulates advanced APIs for uploading and copying. You only need to set the corresponding parameters. The APIs will decide internally whether to perform simple upload/copy or multipart upload/copy based on the file size. Before using the APIs, make sure you have completed the initialization as instructed in [Getting Started] (https://intl.cloud.tencent.com/document/product/436/12266).

    Uploading an object

    Feature description

    This API is used to call a simple upload API operation for small files and a multipart upload API operation for large files based on the file size. Its parameters are the same as those of the PutObject API.

    Sample request

    Sample 1. Uploading an object

    try {
        $result = $cosClient->Upload(
            $bucket = 'examplebucket-1250000000', //Format: BucketName-APPID
            $key = 'exampleobject',
            $body = fopen('path/to/localFile', 'rb')
        );
        // Request successful
        print_r($result);
    } catch (\Exception $e) {
        // Request failed
        echo($e);
    }

    Sample 2. Uploading an archived object

    try {
        $result = $cosClient->Upload(
            $bucket = 'examplebucket-1250000000', //Format: BucketName-APPID
            $key = 'exampleobject',
            $body = fopen('path/to/localFile', 'rb'),
            $options = array(
                'StorageClass' => 'Archive'
            )
        );
        // Request successful
        print_r($result);
    } catch (\Exception $e) {
        // Request failed
        echo($e);
    }

    Sample 3. Uploading an object with metadata by specifying the size of a single part

    try {
        $result = $cosClient->Upload(
            $bucket = 'examplebucket-1250000000', //Format: BucketName-APPID
            $key = 'exampleobject',
            $body = fopen('path/to/localFile', 'rb'),
            $options = array(
                'Metadata' => array(
                    'string' => 'string',
                ),
                'PartSize' => 10 * 1024 * 1024
            )
        );
        // Request successful
        print_r($result);
    } catch (\Exception $e) {
        // Request failed
        echo($e);
    }

    Object Replication

    Feature description

    This API calls the CopyObject API operation for small files and the multipart copy API operation for large files based on the file size. Its parameters are the same as those of the CopyObject API.

    Sample request

    Sample 1. Copying an object

    try {
        $result = $cosClient->Copy(
            $bucket = 'examplebucket-1250000000', //Format: BucketName-APPID
            $key = 'exampleobject',
            $copySorce = array(
                'Region' => 'COS_REGION', 
                'Bucket' => 'sourcebucket-1250000000', 
                'Key' => 'sourceObject', 
            ),
        );
        // Request successful
        print_r($result);
    } catch (\Exception $e) {
        // Request failed
        echo($e);
    }

    Sample 2. Transitioning an object between COS storage classes

    try {
        $result = $cosClient->Copy(
            $bucket = 'examplebucket-1250000000', //Format: BucketName-APPID
            $key = 'exampleobject',
            $copySorce = array(
                'Region' => 'COS_REGION', 
                'Bucket' => 'examplebucket-1250000000', 
                'Key' => 'exampleobject', 
            ),
            $options = array(
                'StorageClass' => 'Archive'
            )
        );
        // Request successful
        print_r($result);
    } catch (\Exception $e) {
        // Request failed
        echo($e);
    }

    Sample 3. Modifying object storage attributes

    try {
        $result = $cosClient->Copy(
            $bucket = 'examplebucket-1250000000', //Format: BucketName-APPID
            $key = 'exampleobject',
            $copySorce = array(
                'Region' => 'COS_REGION', 
                'Bucket' => 'sourcebucket-1250000000', 
                'Key' => 'sourceObject', 
            ),
            $options = array(
                'MetadataDirective' => 'Replaced',
                'Metadata' => array(
                    'string' => 'string',
                ),
            )
        );
        // Request successful
        print_r($result);
    } catch (\Exception $e) {
        // Request failed
        echo($e);
    }

    Was this page helpful?

    Was this page helpful?

    • Not at all
    • Not very helpful
    • Somewhat helpful
    • Very helpful
    • Extremely helpful
    Send Feedback
    Help