Tencent Cloud Documentation

Help & DocumentationCloud Object StorageSDK DocumentationPHP SDKActions on Objects

Actions on Objects

Last updated: 2020-01-10 10:28:27

Overview

This document provides an overview of APIs related to simple object operations, multipart upload, and other operations and corresponding SDK sample code.

Simple operations

API	Operation Name	Operation Description
GET Bucket (List Object)	Querying object list	Queries some or all objects in a bucket
GET Bucket Object Versions	Querying object and historical version list	Queries some or all objects in a bucket and their historical version information
PUT Object	Simply uploading an object	Upload an object (file/object) to a bucket
POST Object	Uploading an object using a form	Uploads an object using format request
HEAD Object	Querying object metadata	Queries object metadata
GET Object	Downloading an object	Downloads an object (file/object) 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 the specified object (file/object) in a bucket
DELETE Multiple Object	Deleting multiple objects	Deletes objects (files/objects) in a bucket in batches

Multipart upload operations

API	Operation Name	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 operation
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 uploaded parts in the 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

Other operations

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

Simple Operations

Querying Object List

Feature Description

This API (List Object) is used to queries all objects in the specified 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 Descriptions

Parameter Name	Type	Description	Required
Bucket	String	Bucket name in the format of BucketName-APPID	Yes
Delimiter	String	Sets the delimiter; for example, set `/` to simulate a folder. This parameter is blank by default	No
EncodingType	String	Specifies the encoding method of the return value; value range: url; no encoding is performed by default	No
Marker	String	Marks the starting position of the list of returned objects. By default, entries are listed in UTF-8 binary order	No
Prefix	String	Filters object keys to match the objects with the specified prefix. This parameter is blank by default	No
MaxKeys	Int	Maximum number of returned objects; default and maximum value: 1,000	No

Return Result Example

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=
        )

)

Return Result Descriptions

Parameter name	Type	Description	Parent Node
Name	String	Bucket name in the format of BucketName-APPID	None
Delimiter	String	Sets the delimiter; for example, set `/` to simulate a folder	None
EncodingType	String	Specifies the encoding method of the return value	None
Marker	String	Marks the starting position of the list of returned objects. By default, entries are listed in UTF-8 binary order	None
Prefix	String	Filters object keys to match the objects with the specified prefix	None
MaxKeys	Int	Maximum number of returned objects; default and maximum value: 1,000	None
IsTruncated	Int	Indicates whether the returned objects are truncated	None
Contents	Array	List of returned objects	None
Content	Array	Attributes of the returned objects including a list of metadata of all objects such as 'ETag', 'StorageClass', 'Key', 'Owner', 'LastModified', and 'Size'	Contents

Querying Object and Historical Version List

Feature Description

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

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 Descriptions

Parameter Name	Type	Description	Required
Bucket	String	Bucket name in the format of BucketName-APPID	Yes
Prefix	String	Filters object keys to match the objects with the specified prefix. This parameter is blank by default	No
Delimiter	String	Sets the delimiter; for example, set `/` to simulate a folder. This parameter is blank by default	No
KeyMarker	String	Marks the starting position of the key in the list of returned objects. By default, entries are listed in UTF-8 binary order	No
VersionIdMarker	String	Marks the starting position of the VersionId in the list of returned objects. By default, entries are listed in UTF-8 binary order	No
MaxKeys	Int	Maximum number of returned objects; default and maximum value: 1,000	No
EncodingType	String	Specifies the encoding method of the return value; value range: url; no encoding is performed by default	No

Return Result Example

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
        )

)

Return Result Descriptions

Parameter name	Type	Description	Parent Node
Name	String	Bucket name in the format of BucketName-APPID	None
Delimiter	String	Sets the delimiter; for example, set `/` to simulate a folder	None
EncodingType	String	Specifies the encoding method of the return value	None
KeyMarker	String	Marks the starting position of the key in the list of returned objects. By default, entries are listed in UTF-8 binary order	None
VersionIdMarker	String	Marks the starting position of the VersionId in the list of returned objects. By default, entries are listed in UTF-8 binary order	None
NextKeyMarker	String	Marks the starting position of the key in the list of objects returned next time if IsTruncated is true	None
NextVersionIdMarker	String	Marks the starting position of the VersionId in the list of objects returned next time if IsTruncated is true	None
Prefix	String	Filters object keys to match the objects with the specified prefix	None
MaxKeys	Int	Maximum number of returned objects; default and maximum value: 1,000	None
IsTruncated	Int	Indicates whether the returned objects are truncated	None
Versions	Array	List of metadata of all multi-version objects	None
Version	Array	List of metadata of all multi-version objects, including information such as 'ETag', 'StorageClass', 'Key', 'VersionId', 'IsLatest', 'Owner', 'LastModified', and 'Size'	Versions
CommonPrefixes	Array	All objects starting with Prefix and ending in Delimiter are grouped into the same class	None

Simply Uploading an Object

Feature Description

This API (PUT Object) is used to upload an object to the specified bucket. It supports files of up to 5 GB in size. If you need to upload larger files, you are recommended to use the advanced composite upload API.

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 Descriptions

Parameter Name	Type	Description	Required
Bucket	String	Bucket name in the format of BucketName-APPID	Yes
Key	String	An object key (Key) is a unique ID of an object in the bucket. For example, in the object's access domain name examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg, the object key is doc/pic.jpg	No
ACL	String	Sets the object ACL such as private and public-read	No
Body	File/String	Uploaded content	Yes
CacheControl	String	Cache policy, which sets Cache-Control	No
ContentDisposition	String	Filename, which sets Content-Disposition	No
ContentEncoding	String	Encoding format, which sets Content-Encoding	No
ContentLanguage	String	Language type, which sets Content-Language	No
ContentLength	Int	Sets transfer length	No
ContentType	String	Content type, which sets Content-Type	No
Expires	String	Sets Content-Expires	No
Metadata	Array	User-defined file metadata	No
StorageClass	String	File storage class; value range: STANDARD, STANDARD_IA, ARCHIVE; default value: STANDARD	No
ContentMD5	String	Sets the MD5 value of the uploaded file for verification	No
ServerSideEncryption	String	Server-side encryption method	No

Return Result Example

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
        )

)

Return Result Descriptions

Parameter name	Type	Description	Parent Node
ETag	String	MD5 value of the uploaded file	None
VersionId	String	File version number after versioning is enabled	None

Querying Object Metadata

Feature Description

This API (HEAD Object) is used to query the metadata of an object.

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 Descriptions

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

Return Result Example

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=
        )

)

Return Result Descriptions

Parameter name	Type	Description	Parent Node
CacheControl	String	Cache policy, which sets Cache-Control	None
ContentDisposition	String	Filename, which sets Content-Disposition	None
ContentEncoding	String	Encoding format, which sets Content-Encoding	None
ContentLanguage	String	Language type, which sets Content-Language	None
ContentLength	Int	Sets transfer length	None
ContentType	String	Content type, which sets Content-Type	None
Metadata	Array	User-defined file metadata	None
StorageClass	String	File storage class; value range: STANDARD, STANDARD_IA, ARCHIVE	None
ServerSideEncryption	String	Server-side encryption method	None
ETag	String	MD5 value of a file	None
Restore	String	Restoration information of an archived file	None

Downloading an Object

Feature Description

This API (GET Object) is used to download an object to the local file system.

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 Descriptions

Parameter Name	Type	Description	Required
Bucket	String	Bucket name in the format of BucketName-APPID	Yes
Key	String	An object key (Key) is a unique ID of an object in the bucket. For example, in the object's access domain name examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg, the object key is doc/pic.jpg	Yes
SaveAs	String	Path to the file saved locally	No
VersionId	String	Specifies a file version if versioning is enabled	No
Range	String	Sets the range of file download in the format of bytes=first-last	No
ResponseCacheControl	String	Sets the response header Cache-Control	No
ResponseContentDisposition	String	Sets the response header Content-Disposition	No
ResponseContentEncoding	String	Sets the response header Content-Encoding	No
ResponseContentLanguage	String	Sets the response header Content-Language	No
ResponseContentType	String	Sets the response header Content-Type	No
ResponseExpires	String	Sets the response header Content-Expires	No

Return Result Example

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
        )

)

Return Result Descriptions

Parameter name	Type	Description	Parent Node
Body	File/String	Downloaded content	None
ETag	String	MD5 value of a file	None
Expires	String	Content-Expires	None
Metadata	Array	User-defined file metadata	None
StorageClass	String	File storage class; value range: STANDARD, STANDARD_IA, ARCHIVE; default value: STANDARD	None
ContentMD5	String	Sets the MD5 value of the uploaded file for verification	None
ServerSideEncryption	String	Server-side encryption method	None
CacheControl	String	Cache policy, which sets Cache-Control	None
ContentDisposition	String	Filename, which sets Content-Disposition	None
ContentEncoding	String	Encoding format, which sets Content-Encoding	None
ContentLanguage	String	Language type, which sets Content-Language	None
ContentLength	Int	Sets transfer length	None
ContentType	String	Content type, which sets Content-Type	None
Metadata	Array	User-defined file metadata	None
Restore	String	Restoration information of an archived file	None

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' => 'examplebucket2-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 Descriptions

Parameter Name	Type	Description	Required
Bucket	String	Bucket name in the format of BucketName-APPID	Yes
Key	String	An object key (Key) is a unique ID of an object in the bucket. For example, in the object's access domain name 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 file to be copied, including Appid, Bucket, Key, and Region, examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg	Yes
MetadataDirective	String	Value range: Copy, Replaced. If this parameter is set to Copy, the configured user metadata is ignored and the copy is performed directly; if Replaced, the metadata is modified based on the configured metadata. If the destination path is the same as the source path, this parameter has to be set to Replaced	No

Deleting a Single Object

Feature Description

This API is used to delete the 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 Descriptions

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

Deleting Multiple Objects

Feature Description

This API is used to delete objects (files/objects) in a bucket in batches.

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 Descriptions

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

Return Result Example

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==
        )
）

Return Result Descriptions

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 of the failure	Errors
Message	String	Error message	Errors

Multipart Upload Operations

Querying a Multipart Upload

Feature Description

This API (List Multipart Uploads) is used to query multipart uploads in progress 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 Descriptions

Parameter Name	Type	Description	Required
Bucket	String	Bucket name in the format of BucketName-APPID	Yes
Delimiter	String	Sets the delimiter; for example, set `/` to simulate a folder. This parameter is blank by default	No
EncodingType	String	Specifies the encoding method of the return value; value range: url; no encoding is performed by default	No
KeyMarker	String	Marks the starting position of the list of returned parts	No
UploadIdMarker	String	Marks the starting position of the list of returned parts	No
Prefix	String	Filters object keys to match the parts with the specified prefix. This parameter is blank by default	No
MaxUploads	Int	Maximum number of returned parts; default and maximum value: 1,000	No

Return Result Example

Return Result Descriptions

Parameter name	Type	Description	Parent Node
Bucket	String	Bucket name in the format of BucketName-APPID	None
IsTruncated	Int	Indicates whether the returned objects are truncated	None
Uploads	Array	List of returned parts	None
Upload	Array	Attribute of returned parts	Uploads
Key	String	Object key name	Upload
UploadId	String	Multipart upload ID of an object	Upload
Initiator	String	The operator who initialized the multipart upload	Upload
Owner	String	Part owner	Upload
StorageClass	String	Part storage class	Upload
Initiated	String	Multipart upload initialization time	Upload

Uploading an Object in Parts

With multipart upload, you can do the following:

Upload an object in parts, including initializing a multipart upload, uploading parts, and completing the multipart upload.
Resume a multipart upload, including querying uploaded parts, uploading parts, and completing the multipart upload.
Delete uploaded parts.

Initializing a Multipart Upload

Feature Description

This API (Initiate Multipart Upload) is used to initialize a multipart upload operation.

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 Descriptions

Parameter Name	Type	Description	Required
Bucket	String	Bucket name in the format of BucketName-APPID	Yes
Key	String	An object key (Key) is a unique ID of an object in the bucket. For example, in the object's access domain name examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg, the object key is doc/pic.jpg	Yes
CacheControl	String	Cache policy, which sets Cache-Control	No
ContentDisposition	String	Filename, which sets Content-Disposition	No
ContentEncoding	String	Encoding format, which sets Content-Encoding	No
ContentLanguage	String	Language type, which sets Content-Language	No
ContentLength	Int	Sets transfer length	No
ContentType	String	Content type, which sets Content-Type	No
Expires	String	Sets Content-Expires	No
Metadata	Array	User-defined file metadata	No
StorageClass	String	File storage class; value range: STANDARD, STANDARD_IA, ARCHIVE; default value: STANDARD	No
ContentMD5	String	Sets the MD5 value of the uploaded file for verification	No
ServerSideEncryption	String	Server-side encryption method	No

Return Result Example

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

)

Return Result Descriptions

Parameter name	Type	Description	Parent Node
Bucket	String	Bucket name in the format of BucketName-APPID	None
Key	String	Object key	None
UploadId	String	Multipart upload ID of an object	None

Querying Uploaded Parts

Feature Description

This API (List Parts) is used to query uploaded parts in the specified 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' => 'NWNhNDY0YzFfMmZiNTM1MGFfNTM2YV8xYjliMTg',
        'PartNumberMarker' => 1,
        'MaxParts' => 1000,
    )); 
    // Request succeeded
    print_r($result);
} catch (\Exception $e) {
    // Request failed
    echo($e);
}

Parameter Descriptions

Parameter Name	Type	Description	Required
Bucket	String	Bucket name in the format of BucketName-APPID	Yes
Key	String	Object key	Yes
UploadId	String	Multipart upload ID of an object	Yes
PartNumberMarker	Int	Marks the starting position of the list of returned parts	No
MaxParts	Int	Maximum number of returned parts; default and maximum value: 1,000	No

Return Result Example

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=
        )

)

Return Result Descriptions

Parameter name	Type	Description	Parent Node
Bucket	String	Bucket name in the format of BucketName-APPID	None
Key	String	Object key	None
UploadId	String	Multipart upload ID of an object	None
IsTruncated	Int	Indicates whether the returned objects are truncated	None
PartNumberMarker	Int	Marks the starting position of the list of returned parts	None
MaxParts	Int	Maximum number of returned parts; default and maximum value: 1,000	None
Initiator	String	The operator who initialized the multipart upload	None
Parts	Array	List of returned parts	None
Part	Array	Attribute of returned parts	Parts
PartNumber	Int	Part number	Part
LastModified	String	Last uploaded time of a part	Part
ETag	String	MD5 value of a part	Part
Size	String	Part size	Part

Uploading Parts

This API (Upload Part) is used to upload a file in 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' => 'NWNhNDY0YzFfMmZiNTM1MGFfNTM2YV8xYjliMTg',
        'PartNumber' => integer,
        /*
        'ContentMD5' => 'string',
        'ContentLength' => integer,
        */
    )); 
    // Request succeeded
    print_r($result);
} catch (\Exception $e) {
    // Request failed
    echo($e);
}

Parameter Descriptions

Parameter Name	Type	Description	Required
Bucket	String	Bucket name in the format of BucketName-APPID	Yes
Key	String	Object key	Yes
UploadId	String	Multipart upload ID of an object	Yes
Body	File/String	Uploaded content	Yes
PartNumber	Int	Uploaded part number	Yes
ContentLength	Int	Sets transfer length	No
ContentMD5	String	Sets the MD5 value of the uploaded file for verification	No

Return Result Example

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

)

Return Result Descriptions

Parameter name	Type	Description	Parent Node
ETag	String	MD5 value of a part	None

Completing a Multipart Upload

Feature Description

The API (Complete Multipart Upload) 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' => '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 Descriptions

Parameter Name	Type	Description	Required
Bucket	String	Bucket name in the format of BucketName-APPID	Yes
Key	String	Object key	Yes
UploadId	String	Multipart upload ID of an object	Yes
Parts	Array	Part information list	Yes
Part	Array	Content information of an uploaded part	Yes
ETag	String	MD5 value of a part	Yes
PartNumber	Int	Part number	Yes

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 Descriptions

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

Other Operations

Restoring an Archived Object

Feature Description

This API (POST Object restore) 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->putObject(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 Descriptions

Parameter Name	Type	Description	Required
Bucket	String	Bucket name in the format of BucketName-APPID	Yes
Key	String	Object key	Yes
Days	String	Sets expiration time of the temporary copy in days	Yes
CASJobParameters	Array	Restoration information	Yes
Tier	String	For data restoration, Tier can specify the restoration type supported by CAS, including Expedited, Standard, and Bulk	Yes

Setting Object ACL

Feature Description

This API (PUT Object acl) is used to set the access control list (ACL) for the specified 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 Descriptions

Parameter Name	Type	Description	Required
Bucket	String	Bucket name in the format of BucketName-APPID	Yes
Key	String	Object key	Yes
Grants	Array	ACL permission list	No
Grant	Array	ACL permission information	No
Grantee	Array	ACL permission information	No
Type	String	Owner permission type	No
Permission	String	Permission type. Value range: FULL_CONTROL, WRITE, READ	No
ACL	String	Overall permission type. Value range: private, public-read	No
Owner	String	Bucket owner information	No
DisplayName	String	Permission owner name	No
ID	String	Permission owner ID	No

Getting Object ACL

Feature Description

This API (GET Object acl) is used to get the access control list (ACL) of the specified 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);
}

Return Result Example

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=
        )
)

Return Result Descriptions

Parameter name	Type	Description	Parent Node
Grants	Array	ACL permissions list	None
Grant	Array	ACL permission information	Grants
Grantee	Array	ACL permission information	Grant
Permission	String	Permission type. Value range: FULL_CONTROL, WRITE, READ	Grant
Owner	String	Bucket owner information	None
DisplayName	String	Permission owner name	Grantee / Owner
ID	String	Permission owner ID	Grantee / Owner

Advanced API (Recommended)

This section describes the advanced API provided by COS that encapsulate the upload and copy operations. You only need to set the corresponding parameters, and the API will decide whether to perform simple upload/copy or multipart upload/copy according to the file size. Please confirm that the initialization as described in Getting Started has been completed before you use this API.

Composite Upload

Feature Description

Based on the file size, this API internally calls the simple upload API for small files or multipart upload API for large files.

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);
}

Composite Copy

Feature Description

Based on the file size, this API internally calls the setting object replication API for small files or multipart copy API for large files.

Sample Request

try {
    $result = $cosClient->Copy(
        $bucket = 'examplebucket-1250000000', // Format: BucketName-APPID
        $key = 'exampleobject',
        $copysource = 'examplebucket2-1250000000.cos.ap-guangzhou.myqcloud.com/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: Bucket Management

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.

Tencent Cloud Documentation

Actions on Objects

Contents：

Overview

Simple Operations

Querying Object List

Feature Description

Method Prototype

Sample Request

Parameter Descriptions

Return Result Example

Return Result Descriptions

Querying Object and Historical Version List

Feature Description

Method Prototype

Sample Request

Parameter Descriptions

Return Result Example

Return Result Descriptions

Simply Uploading an Object

Feature Description

Method Prototype

Sample Request

Parameter Descriptions

Return Result Example

Return Result Descriptions

Querying Object Metadata

Feature Description

Method Prototype

Sample Request

Parameter Descriptions

Return Result Example

Return Result Descriptions

Downloading an Object

Feature Description

Method Prototype

Sample Request

Parameter Descriptions

Return Result Example

Return Result Descriptions

Setting Object Replication

Method Prototype

Sample Request

Parameter Descriptions

Deleting a Single Object

Feature Description

Method Prototype

Sample Request

Parameter Descriptions

Deleting Multiple Objects

Feature Description

Method Prototype

Sample Request

Parameter Descriptions

Return Result Example

Return Result Descriptions

Multipart Upload Operations

Querying a Multipart Upload

Feature Description

Method Prototype

Sample Request

Parameter Descriptions

Return Result Example

Return Result Descriptions

Uploading an Object in Parts

Initializing a Multipart Upload

Feature Description

Method Prototype

Sample Request

Parameter Descriptions

Return Result Example

Return Result Descriptions

Querying Uploaded Parts

Feature Description

Method Prototype

Sample Request

Parameter Descriptions

Return Result Example

Return Result Descriptions

Uploading Parts