Tencent Cloud Documentation

Help & DocumentationCloud Object StorageSDK DocumentationPHP SDKActions on Objects

Actions on Objects

Last updated: 2020-03-30 16:17:36

Introduction

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

Simple Operations

API	Operation	Description
GET Bucket（List Object）	Querying object list	Queries some or all objects in a bucket
GET Bucket Object Versions	Querying list of current and historical versions of objects	Queries some or all objects in a bucket and their historical versions
PUT Object	Uploading 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 (file) to the local file system
PUT Object - Copy	Setting object replication	Copies a file to the destination path
DELETE Object	Deleting a single object	Deletes a specified object in the bucket
DELETE Multiple Objects	Deleting multiple objects	Deletes multiple objects from a bucket in a single request

Multipart Upload Operations

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

Other Operations

API	Operation	Description
POST Object restore	Restoring an archived object	Restores an archived object for access
PUT Object acl	Setting the object ACL	Sets an ACL for an object (file) in the bucket
GET Object acl	Querying object ACL	Queries the ACL of an object (file)

Simple Operations

Querying Object List

Feature Description

This API (List Object) is used to query all objects in a bucket.

Method Prototype

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

Sample Request

try {
    $result = $cosClient->listObjects(array(
        'Bucket' => 'examplebucket-1250000000', //Format：BucketName-APPID
        'Delimiter' => '/',
        'EncodingType' => 'url',
        'Marker' => 'doc/picture.jpg',
        'Prefix' => 'doc',
        'MaxKeys' => 1000,
    )); 
    // Request succeeded
    print_r($result);
} catch (\Exception $e) {
    // Request failed
    echo($e);
}

Parameter Description

Parameter Name	Type	Description	Required
Bucket	String	Bucket name. Format: BucketName-APPID	Yes
Delimiter	String	A separator which is left empty by default. For example, you can specify it as `/` to indicate folders.	String
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 list of returned objects. Entries are listed using UTF-8 binary order by default.	No
Prefix	String	Filters the keys of objects by matching the objects prefixed with this parameter. It is left empty by default.	No
MaxKeys	Int	The maximum number of returned objects. It defaults to 1000.	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=
        )

)

Returned Result

Parameter Name	Type	Description	Parent Node
Bucket	String	Bucket name. Format: BucketName-APPID	Yes
Delimiter	String	A separator which is left empty by default. For example, you can specify it as `/` to indicate folders.	String
EncodingType	String	Specifies the encoding type of the returned value	No
Marker	Marks the starting point of the list of returned objects. Entries are listed using UTF-8 binary order by default.	string	No
Prefix	String	Filters the keys of objects by matching the objects prefixed with this parameter.	No
MaxKeys	Int	The maximum number of returned objects. It defaults to 1000.	No
IsTruncated	Int	Indicates whether the returned objects are truncated	No
Contents	Array	Returned list of objects	No
The list containing the meta information of all objects, including 'ETag', 'StorageClass', 'Key', 'Owner', 'LastModified', 'Size', etc.

Query Objects and the List of Previous Versions

Feature Description

Queries a part of or all objects and previous versions in a bucket

Method Prototype

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

Sample Request

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

Parameter Description

Parameter Name	Type	Description	Required
Bucket	String	Bucket name. Format: BucketName-APPID	Yes
Prefix	Filters the object key by matching the objects prefixed with this parameter. It is left empty by default.	String	No
Delimiter	String	A separator which is left empty by default. For example, you can specify it as `/` to indicate folders.	String
Marker	Marks the starting point of key of the list of returned objects. Entries are listed using UTF-8 binary order by default.	String	No
VersionIdMarker	Marks the starting point of VersionId of the list of returned objects. Entries are listed using UTF-8 binary order by default.	String	No
MaxKeys	The maximum number of returned objects. It defaults to 1000.	int	No
EncodingType	String	Indicates the encoding method of the returned value. The value is not encoded by default. Available 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
        )

)

Returned Result

Parameter Name	Type	Description	Parent Node
Bucket	String	Bucket name. Format: BucketName-APPID	Yes
Delimiter	String	A separator which is left empty by default. For example, you can specify it as `/` to indicate folders.	String
EncodingType	String	Specifies the encoding type of the returned value	No
KeyMarker	String	Marks the starting point of key of the list of returned objects. Entries are listed using UTF-8 binary order by default.	No
VersionIdMarker	String	Marks the starting point of VersionId of the list of returned objects. Entries are listed using UTF-8 binary order by default.	No
	NextKeyMarker	String	Marks the starting point of the next list of returned objects if IsTruncated is true.
NextVersionIdMarker	String	Marks the starting point of VersionId of the next list of returned objects if IsTruncated is true.	No
Prefix	String	Filters the keys of objects by matching the objects prefixed with this parameter.	No
MaxKeys	Int	The maximum number of returned objects. It defaults to 1000.	No
IsTruncated	Int	Indicates whether the returned objects are truncated	No
Versions	Array	List containing metadata of all the versions of objects	No
Versions	Array	List containing metadata of all the versions of objects, including 'ETag'，'StorageClass'，'Key'，'VersionId'，'IsLatest'，'Owner'，'LastModified'，and 'Size'	Versions
CommonPrefixes	Array	All objects starting with Prefix and ending with Delimiter are grouped into the same type	No

Uploading an Object Using Simple Upload

Feature Description

This API (PUT Object) is used to upload an object to a specified bucket. The uploaded object has a size restriction of 5GB. Please use Multipart Upload or Advanced APIs to upload objects greater than 5GB.

Method Prototype

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

Sample Request

try { 
    $result = $cosClient->putObject(array( 
        'Bucket' => 'examplebucket-1250000000', //Format：BucketName-APPID 
        'Key' => 'exampleobject', 
        'Body' => fopen('/data/exampleobject', 'rb'), 
        /*
        'ACL' => 'string',
        'CacheControl' => 'string',
        'ContentDisposition' => 'string',
        'ContentEncoding' => 'string',
        'ContentLanguage' => 'string',
        'ContentLength' => integer,
        'ContentType' => 'string',
        'Expires' => 'string',
        'GrantFullControl' => 'string',
        'GrantRead' => 'string',
        'GrantWrite' => 'string',
        'Metadata' => array(
        'string' => 'string',
        ),
        'ContentMD5' => 'string',
        'ServerSideEncryption' => 'string',
        'StorageClass' => 'string'
        */
    )); 
    // Request succeeded 
    print_r($result); 
} catch (\Exception $e) { 
    // Request failed 
    echo($e); 
}

Parameter Description

Parameter Name	Type	Description	Required
Bucket	String	Bucket name. Format: BucketName-APPID	Yes
Key	String	ObjectKey is the unique identifier of the object in the bucket. For example, in the object's access domain name `examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg`, the ObjectKey is `doc/pic.jpg`	No
ACL	String	Sets ACL of object. For example `private`，`public-read`	No
Body	File/String	Content to be uploaded	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 transmission length	No
ContentType	String	Content Type. Sets Content-Type	No
Expires	String	Sets Content-Expires	No
Metadata	Array	File metadata customized by the user	No
StorageClass	String	Sets the object storage class; Options: STANDARD, STANDARD_IA, ARCHIVE. Default value: STANDARD	No
ContentMD5	String	Set MD5 of the file to be uploaded for verification	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
        )

)

Returned Result

Parameter Name	Type	Description	Parent Node
ETag	String	MD5 of the uploaded file	No
VersionId	String	The version ID of the file when versioning is enabled.	No

Querying Object Metadata

Feature Description

The API (HEAD Object) is used to query object metadata.

Method Prototype

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

Sample Request

$cosClient = new Qcloud\Cos\Client(
    array(
        'region' => $region,
        'schema' => 'https', //Protocol header; http by default
        'credentials'=> array(
            'secretId'  => $secretId ,
            'secretKey' => $secretKey)));
try {
    $result = $cosClient->headObject(array(
        'Bucket' => 'examplebucket-1250000000', //Format：BucketName-APPID
        'Key' => 'exampleobject',
    )); 
    // Request succeeded
    print_r($result);
} catch (\Exception $e) {
    // Request failed
    echo($e);
}

Parameter Description

Parameter Name	Type	Description	Required
Bucket	String	Bucket name. Format: BucketName-APPID	Yes
Key	String	ObjectKey is the unique identifier of the object in the bucket. For example, in the object's access domain name `examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg`, the ObjectKey is `doc/pic.jpg`	Yes
VersionId	String	The version ID of the specified file when 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=
        )

)

Returned Result

Parameter Name	Type	Description	Parent Node
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 transmission length	No
ContentType	String	Content Type. Sets Content-Type	No
Metadata	Array	File metadata customized by the user	No
StorageClass	String	Sets the object storage class; Options: STANDARD, STANDARD_IA, ARCHIVE	No
ServerSideEncryption	String	Server side encryption method	No
ETag	String	MD5 of the file	No
Restore	String	Restoration information of an archived file	No

Downloading an Object

Feature Description

This API (Get Object) is used to download an object locally.

Method Prototype

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

Sample Request

try {
    $result = $cosClient->getObject(array(
        'Bucket' => 'examplebucket-1250000000', //Format：BucketName-APPID
        'Key' => 'exampleobject',
        'SaveAs' => '/data/exampleobject',
        /*
        'Range' => 'bytes=0-10',
        'VersionId' => 'string',
        'ResponseCacheControl' => 'string',
        'ResponseContentDisposition' => 'string',
        'ResponseContentEncoding' => 'string',
        'ResponseContentLanguage' => 'string',
        'ResponseContentType' => 'string',
        'ResponseExpires' => 'string',
        */
    )); 
    // Request succeeded
    print_r($result);
} catch (\Exception $e) {
    // Request failed
    echo($e);
}

Parameter Description

Parameter Name	Type	Description	Required
Bucket	String	Bucket name. Format: BucketName-APPID	Yes
Key	String	ObjectKey is the unique identifier of the object in the bucket. For example, in the object's access domain name `examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg`, the ObjectKey is `doc/pic.jpg`	Yes
SaveAs	String	Path of the file saved locally	No
VersionId	String	The version ID of the specified file when versioning is enabled.	No
Range	String	Sets the range of bytes of the file to be downloaded in the format of 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
        )

)

Returned Result

Parameter Name	Type	Description	Parent Node
Body	File/String	Content to be downloaded	No
ETag	String	MD5 of the file	No
Expires	String	Content-Expires	No
Metadata	Array	File metadata customized by the user	No
StorageClass	String	Sets the object storage class; Options: STANDARD, STANDARD_IA, ARCHIVE. Default value: STANDARD	No
ContentMD5	String	Set MD5 of the file to be uploaded for verification	No
ServerSideEncryption	String	Server side encryption method	No
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 transmission length	No
ContentType	String	Content Type. Sets Content-Type	No
Metadata	Array	File metadata customized by the user	No
Restore	String	Restoration information of an archived file	No

Setting Object Replication

This API (PUT Object - Copy) is used to copy an object to the destination path.

Method Prototype

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

Sample Request

try {
    $result = $cosClient->copyObject(array(
        'Bucket' => 'examplebucket-1250000000', //Format：BucketName-APPID
        'Key' => 'exampleobject',
        'CopySource' => 'sourcebucket-1250000000.cos.ap-guangzhou.myqcloud.com/exampleobject',
        /*
        'MetadataDirective' => 'string',
        'ACL' => 'string',
        'CacheControl' => 'string',
        'ContentDisposition' => 'string',
        'ContentEncoding' => 'string',
        'ContentLanguage' => 'string',
        'ContentLength' => integer,
        'ContentType' => 'string',
        'Expires' => 'string',
        'GrantFullControl' => 'string',
        'GrantRead' => 'string',
        'GrantWrite' => 'string',
        'Metadata' => array(
        'string' => 'string',
        ),
        'ContentMD5' => 'string',
        'ServerSideEncryption' => 'string',
        'StorageClass' => 'string'
        */
    )); 
    // Request succeeded
    print_r($result);
} catch (\Exception $e) {
    // Request failed
    echo($e);
}

Parameter Description

Parameter Name	Type	Description	Required
Bucket	String	Bucket name. Format: BucketName-APPID	Yes
Key	String	ObjectKey is the unique identifier of the object in the bucket. For example, in the object's access domain name `examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg`, the ObjectKey is `doc/pic.jpg`	Yes
CopySource	String	Path of the file to be copied, includes Appid、Bucket、Key、Region， For example, `examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg`	Yes
MetadataDirective	String	Available values: Copy and Replaced. When it is set to Copy, ignore the configured user metadata information and copy the file directly. When it is set to Replaced, modify the metadata according to the configured meta information. If the destination path is identical to the source path, it must be set to Replaced.	Yes

Deleting a Single Object

Feature Description

This API (DELETE Object) is used to delete a specified object (file/object) in 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' => 'string'
    )); 
    // Request succeeded
    print_r($result);
} catch (\Exception $e) {
    // Request failed
    echo($e);
}

Parameter Description

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

Deleting Multiple Objects

Feature Description

This API (DELETE Multiple Object) is used to batch 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 succeeded
    print_r($result);
} catch (\Exception $e) {
    // Request failed
    echo($e);
}

Parameter Description

Parameter Name	Type	Description	Required
Bucket	String	Bucket name. Format: BucketName-APPID	Yes
Objects	Array	List of objects to be deleted	Yes
Objects	Array	Objects to be deleted	Yes
Key	String	ObjectKey is the unique identifier of the object in the bucket. For example, in the object's access domain name `examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg`, the ObjectKey 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==
        )
）

Returned Result

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

Multipart Operations

Query multipart upload

Feature Description

This API (List Multipart Uploads) is used to query in-progress multipart uploads in the 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' => 'string',
        'UploadIdMarker' => 'string',
        'Prefix' => 'prfix',
        'MaxUploads' => 1000,
    )); 
    // Request succeeded
    print_r($result);
} catch (\Exception $e) {
    // Request failed
    echo($e);
}

Parameter Description

Parameter Name	Type	Description	Required
Bucket	String	Bucket name. Format: BucketName-APPID	Yes
Delimiter	String	A separator which is left empty by default. For example, you can specify it as `/` to indicate folders.	String
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 point of the list of returned parts	No
UploadIdMarker	String	Marks the starting point of the list of returned parts	No
Prefix	String	Filters the keys of parts by matching the objects prefixed with this parameter. It is left empty by default.	No
MaxUploads	Int	The maximum number of returned parts. It defaults to 1000.	No

Sample Response

Returned Result

Parameter Name	Type	Description	Parent Node
Bucket	String	Bucket name. Format: BucketName-APPID	Yes
IsTruncated	Int	Indicates whether the returned objects are truncated	No
Uploads	Array	Returned list of parts	No
Upload	Array	Returned parts attributes	Uploads
Key	String	Object key name	Upload
UploadId	String	Multipart upload ID of an object	Upload
Initiator	String	User who initiated the multipart upload	Upload
Owner	String	Owner of the parts	Upload
StorageClass	String	Storage class of the parts	Upload
Initiated	String	Time the multipart upload was initiated	Upload

Upload an object using multipart upload

This includes the following operations:

Uploading an object in multiple parts: initialize multipart upload, upload parts, and complete the upload of all parts.
Resuming a multipart upload: query uploaded parts, upload parts, and complete the upload of all parts
Deleting uploaded parts.

Initializing-multipart-upload-">

Initializing multipart upload

Feature Description

This API (Initiate Multipart Upload) initializes a multipart upload task.

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',
        /*  
        'CacheControl' => 'string',
        'ContentDisposition' => 'string',
        'ContentEncoding' => 'string',
        'ContentLanguage' => 'string',
        'ContentLength' => integer,
        'ContentType' => 'string',
        'Expires' => 'string',
        'Metadata' => array(
            'string' => 'string',
        ),
        'StorageClass' => 'string'
        */
    )); 
    // Request succeeded
    print_r($result);
} catch (\Exception $e) {
    // Request failed
    echo($e);
}

Parameter Description

Parameter Name	Type	Description	Required
Bucket	String	Bucket name. Format: BucketName-APPID	Yes
Key	String	ObjectKey is the unique identifier of the object in the bucket. For example, in the object's access domain name `examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg`, the ObjectKey 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 transmission length	No
ContentType	String	Content Type. Sets Content-Type	No
Expires	String	Sets Content-Expires	No
Metadata	Array	File metadata customized by the user	No
StorageClass	String	Sets the object storage class; Options: STANDARD, STANDARD_IA, ARCHIVE. Default value: STANDARD	No
ContentMD5	String	Set MD5 of the file to be uploaded for verification	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=
        )

)

Returned Result

Parameter Name	Type	Description	Parent Node
Bucket	String	Bucket name. Format: BucketName-APPID	Yes
Key	String	Object Key	No
UploadId	String	ID of multipart upload	No

-Querying-a-Multipart-Upload-">

Querying a Multipart Upload

Feature Description

This API (List Parts) is used to query the uploaded parts in a specific multipart upload process.

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' => 'NWNhNDY0YzFfMmZiNTM1MGFfNTM2YV8xYjliMTg',
        'PartNumberMarker' => 1,
        'MaxParts' => 1000,
    )); 
    // Request succeeded
    print_r($result);
} catch (\Exception $e) {
    // Request failed
    echo($e);
}

Parameter Description

Parameter Name	Type	Description	Required
Bucket	String	Bucket name. Format: BucketName-APPID	Yes
Key	String	Object Key	Yes
UploadId	String	ID of multipart upload	Yes
PartNumberMarker	Int	Marks the starting point of the list of returned parts	No
MaxParts	Int	The maximum number of returned parts. It defaults to 1000.	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=
        )

)

Returned Result

Parameter Name	Type	Description	Parent Node
Bucket	String	Bucket name. Format: BucketName-APPID	Yes
Key	String	Object Key	No
UploadId	String	ID of multipart upload	No
IsTruncated	Int	Indicates whether the returned objects are truncated	No
PartNumberMarker	Int	Marks the starting point of the list of returned parts	No
MaxParts	Int	The maximum number of returned parts. It defaults to 1000.	No
Initiator	String	User who initiated the multipart upload	No
Parts	Array	Returned list of parts	No
Part	Array	Returned parts attributes	Parts
PartNumber	Int	Part identifier	Part
LastModified	String	Time the parts were last uploaded	Part
ETag	String	MD5 of the part	Part
Size	String	Part size	Part

-Uploading-Parts">

Uploading Parts

This API (Upload Part) is used to upload a part.

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' => 'NWNhNDY0YzFfMmZiNTM1MGFfNTM2YV8xYjliMTg', // Multipart upload ID of an object. Returned in the response of Initiate Multipart Upload 
        'PartNumber' => integer, // Part serial number. COS merges parts according to the part serial number
        /*
        'ContentMD5' => 'string',
        'ContentLength' => integer,
        */
    )); 
    // Request succeeded
    print_r($result);
} catch (\Exception $e) {
    // Request failed
    echo($e);
}

Parameter Description

Parameter Name	Type	Description	Required
Bucket	String	Bucket name. Format: BucketName-APPID	Yes
Key	String	Object Key	Yes
UploadId	String	Multipart upload ID of an object. Returned in the response of Initiate Multipart Upload	Yes
Body	File/String	Content to be uploaded	Yes
PartNumber	Int	Part serial number. COS merges parts according to the part serial number	Yes
ContentLength	Int	Sets transmission length	No
ContentMD5	String	Set MD5 of the file to be uploaded for verification	No

Sample Response

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

)

Returned Result

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

-Completing-a-Multipart-Upload-">

Completing a Multipart Upload

Feature Description

This API (Complete Multipart Upload) is used to complete the entire multipart upload.

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' => 'string',
        'Parts' => array(
            array(
                'ETag' => 'string',
                'PartNumber' => integer,
            ),  
            array(
                'ETag' => 'string',
                'PartNumber' => integer,
            )), 
            // ... repeated
    )); 
    // Request succeeded
    print_r($result);
} catch (\Exception $e) {
    // Request failed
    echo($e);
}

Parameter Description

Parameter Name	Type	Description	Required
Bucket	String	Bucket name. Format: BucketName-APPID	Yes
Key	String	Object Key	Yes
UploadId	String	ID of multipart upload	Yes
Parts	Array	List of parts information	Yes
Part	Array	Part information	Yes
ETag	String	MD5 of the part	No
PartNumber	Int	Part number	Yes

-Aborting-a-Multipart-Upload-">

Aborting a Multipart Upload

Feature Description

This API (Abort Multipart Upload) is used to abort a multipart upload operation 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' => 'string',
    )); 
    // Request succeeded
    print_r($result);
} catch (\Exception $e) {
    // Request failed
    echo($e);
}

Parameter Description

Parameter Name	Type	Description	Required
Bucket	String	Bucket name. Format: BucketName-APPID	Yes
Key	String	Object Key	Yes
UploadId	String	ID of multipart upload	Yes

Other Operations

Restoring an Archived Object

Feature Description

This API (POST Object restore) is used to restore an archived object.

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' => integer,
        'CASJobParameters' => array(
            'Tier' =>'string'
        )    
    )); 
    // Request succeeded
    print_r($result);
} catch (\Exception $e) {
    // Request failed
    echo($e);
}

Parameter Description

Parameter Name	Type	Description	Required
Bucket	String	Bucket name. Format: BucketName-APPID	Yes
Key	String	Object Key	Yes
Days	String	Sets the validity period of the temporary replica in days	Yes
CASJobParameters	Array	Restore information	Yes
Tier	String	When restoring data, Tier can be specified as three types of restoration supported by CAS: Expedited, Standard, and Bulk.	Yes

Setting Object ACL

Feature Description

This API (Put Object ACL) is used to set an ACL for an object.

Method Prototype

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

Sample Request

try {
    $result = $cosClient->putObjectAcl(array(
        'Bucket' => 'examplebucket-1250000000', //Format：BucketName-APPID
        'Key' => 'exampleobject',
        'ACL' => 'private',
        'Grants' => array(
            array(
                'Grantee' => array(
                    'DisplayName' => 'qcs::cam::uin/100000000001:uin/100000000001',
                    'ID' => 'qcs::cam::uin/100000000001:uin/100000000001',
                    'Type' => 'CanonicalUser',
                ),  
                'Permission' => 'FULL_CONTROL',
            ),  
            // ... repeated
        ),  
        'Owner' => array(
            'DisplayName' => 'qcs::cam::uin/100000000001:uin/100000000001',
            'ID' => 'qcs::cam::uin/100000000001:uin/100000000001',
        )));
    // Request succeeded
    print_r($result);
} catch (\Exception $e) {
    // Request failed
    echo "$e\n";
}

Parameter Description

Parameter Name	Type	Description	Required
Bucket	String	Bucket name. Format: BucketName-APPID	Yes
Key	String	Object Key	Yes
Grants	Array	ACL permissions information	No
Grant	Array	ACL permissions information	No
Grantee	Array	ACL permissions information	No
Type	String	Authorized user’s permission type	No
Permission	String	Permission type. Valid values: FULL_CONTROL, WRITE, READ	No
ACL	String	Overall permission type. Valid values: private, public-read	No
Owner	String	Bucket owner information	No
DisplayName	String	Name of the authorized user	string
ID	String	Authorized user ID	No

Get the object ACL

Feature Description

This API (Get Object ACL) is used to get the ACL of an object.

Method Prototype

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

Sample Request

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

Sample Response

Array
(
    [data:protected] => Array
        (
            [Owner] => Array
                (
                    [ID] => qcs::cam::uin/100000000001:uin/100000000001
                    [DisplayName] => qcs::cam::uin/100000000001:uin/100000000001
                )

            [Grants] => Array
                (
                    [0] => Array
                        (
                            [Grantee] => Array
                                (
                                    [ID] => qcs::cam::uin/100000000001:uin/100000000001
                                    [DisplayName] => qcs::cam::uin/100000000001:uin/100000000001
                                )

                            [Permission] => FULL_CONTROL
                        )

                )

            [RequestId] => NWE3YzhjMTRfYzdhMzNiMGFfYjdiOF8yYzZmMzU=
        )
)

Returned Result

Parameter Name	Type	Description	Parent Node
Grants	Array	ACL permissions information	No
Grant	Array	ACL permissions information	Grants
Grantee	Array	ACL permissions information	Grant
Permission	String	Permission type. Valid values: FULL_CONTROL, WRITE, READ	Grant
Owner	String	Bucket owner information	No
DisplayName	String	Authorized user name	Grantee / Owner
ID	String	Authorized user ID	Grantee/Owner

Advanced APIs (Recommended)

This section encapsulates advanced APIs for uploading and copying. The user only needs 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 API, make sure you have completed initialization as instructed in Getting Started.

Object Uploading

Feature Description

This API automatically selects between simple upload and multipart upload according to the file size.

Sample Request

try {
    $result = $cosClient->Upload(
        $bucket = 'examplebucket-1250000000', //Format：BucketName-APPID
        $key = 'exampleobject',
        $body = fopen('/data/exampleobject', 'rb')
        /*
        $options = array(
            'ACL' => 'string',
            'CacheControl' => 'string',
            'ContentDisposition' => 'string',
            'ContentEncoding' => 'string',
            'ContentLanguage' => 'string',
            'ContentLength' => integer,
            'ContentType' => 'string',
            'Expires' => 'string',
            'GrantFullControl' => 'string',
            'GrantRead' => 'string',
            'GrantWrite' => 'string',
            'Metadata' => array(
                'string' => 'string',
            ),
            'ContentMD5' => 'string',
            'ServerSideEncryption' => 'string',
            'StorageClass' => 'string'
        )
        */
    );
    // Request succeeded
    print_r($result);
} catch (\Exception $e) {
    // Request failed
    echo($e);
}

Object Replication

Feature Description

This API automatically selects between simple replication and multipart replication according to the file size.

Sample Request

try {
    $result = $cosClient->Copy(
        $bucket = 'examplebucket-1250000000', //Format：BucketName-APPID
        $key = 'exampleobject',
        $copySorce = array(
            'Region' => 'ap-guangzhou', 
            'Bucket' => 'examplebucket2-1250000000', 
            'Key' => 'exampleobject', 
        ),
        /*
        $options = array(
            'ACL' => 'string',
            'MetadataDirective' => 'string',
            'CacheControl' => 'string',
            'ContentDisposition' => 'string',
            'ContentEncoding' => 'string',
            'ContentLanguage' => 'string',
            'ContentLength' => integer,
            'ContentType' => 'string',
            'Expires' => 'string',
            'GrantFullControl' => 'string',
            'GrantRead' => 'string',
            'GrantWrite' => 'string',
            'Metadata' => array(
                'string' => 'string',
            ),
            'ContentMD5' => 'string',
            'ServerSideEncryption' => 'string',
            'StorageClass' => 'string'
        )
        */
    );
    // Request succeeded
    print_r($result);
} catch (\Exception $e) {
    // Request failed
    echo($e);
}

Previous: Actions on Buckets Next: Versioning

Feedback

Sales Support

Contact our sales team or business advisors to help your business.

Technical Support

Open a ticket if you're looking for further assistance. Our Ticket is 7x24 avaliable.

7x24 Phone Support

Hong Kong, China

+852 800-964-163 (Toll Free)

United States

+1 888-652-2736 (Toll Free)

Others

+86 75595716

Tencent Cloud Documentation

Actions on Objects

Contents：

Introduction

Simple Operations

Querying Object List

Feature Description

Method Prototype

Sample Request

Parameter Description

Sample Response

Returned Result

Query Objects and the List of Previous Versions

Feature Description

Method Prototype

Sample Request

Parameter Description

Sample Response

Returned Result

Uploading an Object Using Simple Upload

Feature Description

Method Prototype

Sample Request

Parameter Description

Sample Response

Returned Result

Querying Object Metadata

Feature Description

Method Prototype

Sample Request

Parameter Description

Sample Response

Returned Result

Downloading an Object

Feature Description

Method Prototype

Sample Request

Parameter Description

Sample Response

Returned Result

Setting Object Replication

Method Prototype

Sample Request

Parameter Description

Deleting a Single Object

Feature Description

Method Prototype

Sample Request

Parameter Description

Deleting Multiple Objects

Feature Description

Method Prototype

Sample Request

Parameter Description

Sample Response

Returned Result

Multipart Operations

Query multipart upload

Feature Description

Method Prototype

Sample Request

Parameter Description

Sample Response

Returned Result

Upload an object using multipart upload

Initializing multipart upload

Feature Description

Method Prototype

Sample Request

Parameter Description

Sample Response

Returned Result

Querying a Multipart Upload

Feature Description

Method Prototype

Sample Request

Parameter Description

Sample Response

Returned Result

Uploading Parts