Overview
This document provides an overview of APIs and SDK code samples related to simple operations, multipart operations, and advanced APIs.
Simple operations
API |
Operation |
Description |
GET Bucket (List Objects) |
Querying an object list |
Queries some or all objects in a bucket |
GET Bucket Object Versions |
Querying a list objects and their version history |
Queries some or all objects in a bucket and their version history |
PUT Object |
Uploads an object using simple upload |
Uploads an object to a bucket |
HEAD Object |
Querying object metadata |
Queries the metadata of an object |
GET Object |
Downloading an object |
Downloads an object to the local file system |
PUT Object - Copy |
Copying an object |
Copies a file to a destination path |
DELETE Object |
Deleting a single object |
Deletes a specified object from a bucket |
DELETE Multiple Objects |
Deleting multiple objects |
Deletes multiple objects from a bucket in a single request |
POST Object restore |
Restoring an archived object |
Restores an archived object for access |
Multipart upload operations
API |
Operation |
Description |
List Multipart Uploads |
Querying a multipart upload |
Queries the information about an ongoing multipart upload |
Initiate Multipart Upload |
Initializing a multipart upload |
Initializes a multipart upload task |
Upload Part |
Uploading a part |
Uploads a part in a multipart upload |
Upload Part - Copy |
Copying a part |
Copies an object as part |
List Parts |
Querying uploaded parts |
Queries the uploaded parts of a specified multipart upload operation |
Complete Multipart Upload |
Completing a multipart upload |
Completes the multipart upload of the entire object |
Abort Multipart Upload |
Aborting a multipart upload |
Aborts a multipart upload and deletes the uploaded parts |
Simple Operations
Querying object list
API description
This API is used to query all the objects in a specified bucket.
Method prototype
public Guzzle\Service\Resource\Model listObjects(array $args = array());
Sample request
Sample 1. Querying a list of objects with the specified prefix and starting object
try {
$result = $cosClient->listObjects(array(
'Bucket' => 'examplebucket-1250000000',
'Delimiter' => '',
'EncodingType' => 'url',
'Marker' => 'doc/picture.jpg',
'Prefix' => 'doc',
'MaxKeys' => 1000,
));
print_r($result);
} catch (\Exception $e) {
echo($e);
}
Parameter description
Parameter Name |
Type |
Description |
Required |
Bucket |
String |
Bucket name in the format: BucketName-APPID |
Yes |
Delimiter |
String |
A separator that is left empty by default. For example, you can set it to / to indicate folders. |
No |
EncodingType |
String |
Indicates the encoding method of the returned value. The value is not encoded by default. Valid value: url |
No |
Marker |
String |
Marks the starting point of the returned object list. Entries are listed using UTF-8 binary order by default. |
No |
Prefix |
String |
Filters the object keys prefixed with the value of this parameter. It is left empty by default. |
No |
MaxKeys |
Int |
The maximum number of returned objects. Defaults to 1000 . |
No |
Response sample
Guzzle\Service\Resource\Model Object
(
[structure:protected] =>
[data:protected] => Array
(
[Name] => examplebucket-1250000000
[Prefix] => doc
[Marker] => doc/picture.jpg
[MaxKeys] => 10
[IsTruncated] => 1
[NextMarker] => doc/exampleobject
[Contents] => Array
(
[0] => Array
(
[Key] => doc/exampleobject
[LastModified] => 2019-02-14T12:20:40.000Z
[ETag] => "e37b429559d82e852af0b2f5b4d078ab72b90208"
[Size] => 6532594
[Owner] => Array
(
[ID] => 100000000001
[DisplayName] => 100000000001
)
[StorageClass] => STANDARD
)
[1] => Array
(
[Key] => doc/exampleobject2
[LastModified] => 2019-03-04T06:34:43.000Z
[ETag] => "988f9f28e68eba9b8c1f5f98ccce0a3c"
[Size] => 28
[Owner] => Array
(
[ID] => 100000000001
[DisplayName] => 100000000001
)
[StorageClass] => STANDARD
)
)
[RequestId] => NWNhMzM0MmZfOWUxYzBiMDlfOTk2YV83ZWE3ODE=
)
)
Response description
Parameter Name |
Type |
Description |
Parent Node |
Name |
String |
Bucket name in the format: BucketName-APPID |
None |
Delimiter |
String |
A separator that is left empty by default. For example, you can set it to / to indicate folders. |
None |
EncodingType |
Specifies the encoding type of the returned value |
None |
|
Marker |
String |
Marks the starting point of the returned object list. Entries are listed using UTF-8 binary order by default. |
None |
Prefix |
String |
Filters the object keys prefixed with the value of this parameter. |
None |
MaxKeys |
Int |
The maximum number of returned objects. Defaults to 1000 . |
None |
IsTruncated |
Int |
Indicates whether the returned objects are truncated |
None |
Contents |
Array |
Returned object list |
None |
Content |
Array |
Returned object attributes, contains a list of the metadata of all objects, including 'ETag', 'StorageClass', 'Key', 'Owner', 'LastModified', and 'Size' |
Contents |
Querying objects and their version history
API description
This API is used to query some or all objects in a bucket as well as their version history.
Method prototype
public Guzzle\Service\Resource\Model listObjectVersions(array $args = array());
Sample request
Sample 1. Querying a list of past object versions
try {
$result = $cosClient->listObjectVersions(array(
'Bucket' => 'examplebucket-1250000000',
'Delimiter' => '',
'EncodingType' => 'url',
'KeyMarker' => 'doc/picture.jpg',
'VersionIdMarker' => 'MTg0NDUxODMyMTE2ODY0OTExOTk3W',
'Prefix' => 'doc',
'MaxKeys' => 1000,
));
print_r($result);
} catch (\Exception $e) {
echo($e);
}
Parameter description
Parameter Name |
Type |
Description |
Required |
Bucket |
String |
Bucket name in the format: BucketName-APPID |
Yes |
Prefix |
String |
Filters the object keys prefixed with the value of this parameter. It is left empty by default. |
No |
Delimiter |
String |
A separator that is left empty by default. For example, you can set it to / to indicate folders. |
No |
KeyMarker |
String |
Marks the starting key of the returned object list. Entries are listed in UTF-8 binary order by default. |
No |
VersionIdMarker |
String |
Marks the starting VersionId of the returned object list. Entries are listed in UTF-8 binary order by default. |
No |
MaxKeys |
Int |
The maximum number of returned objects. Defaults to 1000 . |
No |
EncodingType |
String |
Indicates the encoding method of the returned value. The value is not encoded by default. Valid value: url |
No |
Response sample
Guzzle\Service\Resource\Model Object
(
[structure:protected] =>
[data:protected] => Array
(
[Name] => examplebucket-1250000000
[Prefix] => doc
[KeyMarker] => string
[VersionIdMarker] => string
[MaxKeys] => 10
[IsTruncated] => 1
[NextKeyMarker] => string
[NextVersionIdMarker] => string
[Versions] => Array
(
[0] => Array
(
[Key] => doc/exampleobject1
[VersionId] => null
[IsLatest] => 1
[LastModified] => 2019-06-13T09:24:52.000Z
[ETag] => "96e79218965eb72c92a549dd5a330112"
[Size] => 6
[StorageClass] => STANDARD
[Owner] => Array
(
[UID] => 1251668577
)
)
[1] => Array
(
[Key] => doc/exampleobject2
[VersionId] => MTg0NDUxODMyMTE2ODY0OTExOTk
[IsLatest] => 1
[LastModified] => 2019-06-18T12:47:03.000Z
[ETag] => "698d51a19d8a121ce581499d7b701668"
[Size] => 3
[StorageClass] => STANDARD
[Owner] => Array
(
[UID] => 1251668577
)
)
)
[RequestId] => NWQwOGVkZGRfMjViMjU4NjRfODNjN18xMTE5YWI4
)
)
Response description
Parameter Name |
Type |
Description |
Parent Node |
Name |
String |
Bucket name in the format: BucketName-APPID |
None |
Delimiter |
String |
A separator that is left empty by default. For example, you can set it to / to indicate folders. |
None |
EncodingType |
Specifies the encoding type of the returned value |
None |
|
KeyMarker |
String |
Marks the starting key of the returned object list. Entries are listed using UTF-8 binary order by default. |
None |
VersionIdMarker |
String |
Marks the starting VersionId of the returned object list. Entries are listed using UTF-8 binary order by default. |
None |
NextKeyMarker |
String |
Marks the starting key of the next list of returned objects if IsTruncated is true. |
None |
NextVersionIdMarker |
String |
Marks the starting VersionId of the next list of returned objects if IsTruncated is set to true . |
None |
Prefix |
String |
Filters the object keys prefixed with the value of this parameter. |
None |
MaxKeys |
Int |
The maximum number of returned objects. Defaults to 1000 . |
None |
IsTruncated |
Int |
Indicates whether the returned objects are truncated |
None |
Versions |
Array |
An array of metadata on all the versions of each object |
None |
Version |
Array |
List of the metadata of objects with multiple versions, including 'ETag','StorageClass','Key','VersionId','IsLatest','Owner','LastModified',and 'Size' |
Versions |
CommonPrefixes |
Array |
All objects starting with a particular prefix and ending with the delimiter are grouped as a common prefix |
None |
Uploading an object using simple upload
API description
This API (PUT Object) is used to upload an object to a specified bucket. You can upload objects up to 5 GB in size. Please use [Multipart Upload] (#.E5.88.86.E5.9D.97.E6.93.8D.E4.BD.9C) or Advanced APIs to upload objects greater than 5 GB.
Method prototype
public Guzzle\Service\Resource\Model putObject(array $args = array())
Sample request
Sample 1. Uploading a local file
try {
$result = $cosClient->putObject(array(
'Bucket' => 'examplebucket-1250000000',
'Key' => 'exampleobject',
'Body' => fopen('path/to/localFile', 'rb'),
));
print_r($result);
} catch (\Exception $e) {
echo($e);
}
Sample 2. Upload a file to ARCHIVE
try {
$result = $cosClient->putObject(array(
'Bucket' => 'examplebucket-1250000000',
'Key' => 'exampleobject',
'Body' => fopen('path/to/localFile', 'rb'),
'StorageClass' => 'Archive'
));
print_r($result);
} catch (\Exception $e) {
echo($e);
}
Sample 3. Uploading a file with a specified Content-type
try {
$result = $cosClient->putObject(array(
'Bucket' => 'examplebucket-1250000000',
'Key' => 'exampleobject',
'Body' => fopen('path/to/localFile', 'rb'),
'ContentType' => 'text/xml'
));
print_r($result);
} catch (\Exception $e) {
echo($e);
}
Parameter description
Parameter Name |
Type |
Description |
Required |
Bucket |
String |
Bucket name in the format: BucketName-APPID |
Yes |
Key |
String |
Uniquely identifies an object in a bucket. For example, if the object access endpoint is is examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg , its object key is doc/pic.jpg . |
No |
ACL |
String |
ACL of the object, such as private or public-read |
No |
Body |
File/String |
Uploaded content |
Yes |
CacheControl |
String |
Cache policy. Sets Cache-Control . |
No |
ContentDisposition |
String |
File name. Sets Content-Disposition . |
No |
ContentEncoding |
String |
Encoding format. Sets Content-Encoding |
No |
ContentLanguage |
String |
Language type. Sets Content-Language |
No |
ContentLength |
Int |
Sets the length of the request content |
No |
ContentType |
String |
Content type. Sets Content-Type . |
No |
Expires |
String |
Sets Content-Expires . |
No |
Metadata |
Array |
User-defined file metadata |
No |
StorageClass |
String |
Storage class of the object, such as STANDARD (default), STANDARD_IA, and ARCHIVE. For more information, please see Storage Class Overview. |
No |
ContentMD5 |
String |
Sets the MD5 checksum of the uploaded file |
No |
ServerSideEncryption |
String |
Server-side encryption method |
No |
Sample response
Guzzle\Service\Resource\Model Object
(
[structure:protected] =>
[data:protected] => Array
(
[ETag] => "698d51a19d8a121ce581499d7b701668"
[VersionId] => MTg0NDUxODMyMTE2ODY0OTExOTk
[RequestId] => NWQwOGRkNDdfMjJiMjU4NjRfNzVjXzEwNmVjY2M=
[ObjectURL] => http:
)
)
Response description
Parameter Name |
Type |
Description |
Parent Node |
ETag |
String |
MD5 checksum of the uploaded file |
None |
VersionId |
String |
Version ID of the file if versioning is enabled. |
None |
API description
The API is used to query object metadata.
Method prototype
public Guzzle\Service\Resource\Model headObject(array $args = array());
Sample request
try {
$result = $cosClient->headObject(array(
'Bucket' => 'examplebucket-1250000000',
'Key' => 'exampleobject',
));
print_r($result);
} catch (\Exception $e) {
echo($e);
}
Parameter description
Parameter Name |
Type |
Description |
Required |
Bucket |
String |
Bucket name in the format: BucketName-APPID |
Yes |
Key |
String |
Uniquely identifies an object in a bucket. For example, if the object access endpoint is
examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg , its object key is doc/pic.jpg . |
Yes |
VersionId |
String |
Version ID of the specified file if versioning is enabled. |
No |
Response sample
Guzzle\Service\Resource\Model Object
(
[structure:protected] =>
[data:protected] => Array
(
[DeleteMarker] =>
[AcceptRanges] =>
[Expiration] =>
[Restore] =>
[LastModified] => Tue, 02 Apr 2019 12:38:09 GMT
[ContentLength] => 238186
[ETag] => "af9f3b8eaf64473278909183abba1e31"
[MissingMeta] =>
[VersionId] =>
[CacheControl] =>
[ContentDisposition] =>
[ContentEncoding] =>
[ContentLanguage] =>
[ContentType] => text/plain; charset=utf-8
[Expires] =>
[ServerSideEncryption] =>
[Metadata] => Array
(
[md5] => af9f3b8eaf64473278909183abba1e31
)
[SSECustomerAlgorithm] =>
[SSECustomerKeyMD5] =>
[SSEKMSKeyId] =>
[StorageClass] =>
[RequestCharged] =>
[ReplicationStatus] =>
[RequestId] => NWNhMzU3Y2ZfMzFhYzM1MGFfODdhMF8xOTExM2U=
)
)
Response description
Parameter Name |
Type |
Description |
Parent Node |
CacheControl |
String |
Cache policy. Sets Cache-Control . |
None |
ContentDisposition |
String |
File name. Sets Content-Disposition |
None |
ContentEncoding |
String |
Encoding format. Sets Content-Encoding |
None |
ContentLanguage |
String |
Language type. Sets Content-Language |
None |
ContentLength |
Int |
Sets the length of the request content |
None |
ContentType |
String |
Content type. Sets Content-Type . |
None |
Metadata |
Array |
User-defined file metadata |
None |
StorageClass |
String |
Storage class of the object, such as STANDARD, STANDARD_IA, and ARCHIVE. For more information, please see Storage Class Overview. |
No |
ServerSideEncryption |
String |
Server-side encryption method |
None |
ETag |
String |
MD5 checksum of the file |
None |
Restore |
String |
Restoration information of the archived file |
None |
Downloading an object
API description
This API is used to download an object.
Method prototype
public Guzzle\Service\Resource\Model getObject(array $args = array());
Sample request
Sample 1. Download a file
try {
$result = $cosClient->getObject(array(
'Bucket' => 'examplebucket-1250000000',
'Key' => 'exampleobject',
'SaveAs' => 'path/to/localFile',
));
} catch (\Exception $e) {
echo($e);
}
Sample 2. Getting file content within a certain byte range
try {
$result = $cosClient->getObject(array(
'Bucket' => 'examplebucket-1250000000',
'Key' => 'exampleobject',
'Range' => 'bytes=0-10'
));
print_r($result);
} catch (\Exception $e) {
echo($e);
}
Sample 3. Downloading a file with a specified version ID
try {
$result = $cosClient->getObject(array(
'Bucket' => 'examplebucket-1250000000',
'Key' => 'exampleobject',
'VersionId' => 'exampleVersionId'
));
print_r($result);
} catch (\Exception $e) {
echo($e);
}
Parameter description
Parameter Name |
Type |
Description |
Required |
Bucket |
String |
Bucket name in the format: BucketName-APPID |
Yes |
Key |
String |
Uniquely identifies an object in a bucket. For example, if the object access endpoint is
examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg , its object key is doc/pic.jpg . |
Yes |
SaveAs |
String |
Local path for saving the file |
No |
VersionId |
String |
Version ID of the specified file if versioning is enabled |
No |
Range |
String |
Sets the byte range of the file to be downloaded in the format: bytes=first-last |
No |
ResponseCacheControl |
String |
Sets the Cache-Control in the response header |
No |
ResponseContentDisposition |
String |
Sets the Content-Disposition in the response header |
No |
ResponseContentEncoding |
String |
Sets the Content-Encoding in the response header |
No |
ResponseContentLanguage |
String |
Sets the Content-Language in the response header |
No |
ResponseContentType |
String |
Sets the Content-Type in the response header |
No |
ResponseExpires |
String |
Sets the Content-Expires in the response header |
No |
Response sample
Guzzle\Service\Resource\Model Object
(
[structure:protected] =>
[data:protected] => Array
(
[Body] =>
[DeleteMarker] =>
[AcceptRanges] => bytes
[Expiration] =>
[Restore] =>
[LastModified] => Tue, 02 Apr 2019 20:38:09 GMT
[ContentLength] => 238186
[ETag] => "af9f3b8eaf64473278909183abba1e31"
[MissingMeta] =>
[VersionId] =>
[CacheControl] =>
[ContentDisposition] =>
[ContentEncoding] =>
[ContentLanguage] =>
[ContentRange] =>
[ContentType] => text/plain; charset=utf-8
[Expires] =>
[WebsiteRedirectLocation] =>
[ServerSideEncryption] =>
[Metadata] => Array
(
[md5] => af9f3b8eaf64473278909183abba1e31
)
[SSECustomerAlgorithm] =>
[SSECustomerKeyMD5] =>
[SSEKMSKeyId] =>
[StorageClass] =>
[RequestCharged] =>
[ReplicationStatus] =>
[RequestId] => NWNhNDBmYzBfNmNhYjM1MGFfMmUzYzFfMWIzMDYz
)
)
Response description
Parameter Name |
Type |
Description |
Parent Node |
Body |
File/String |
Downloaded content |
None |
ETag |
String |
MD5 checksum of the file |
None |
Expires |
String |
Content-Expires |
None |
Metadata |
Array |
User-defined file metadata |
None |
StorageClass |
String |
Storage class of the object, such as STANDARD (default), STANDARD_IA, and ARCHIVE. For more information, please see Storage Class Overview. |
No |
ContentMD5 |
String |
Sets the MD5 checksum of the uploaded file |
None |
ServerSideEncryption |
String |
Server-side encryption method |
None |
CacheControl |
String |
Cache policy. Sets Cache-Control . |
None |
ContentDisposition |
String |
File name. Sets Content-Disposition |
None |
ContentEncoding |
String |
Encoding format. Sets Content-Encoding |
None |
ContentLanguage |
String |
Language type. Sets Content-Language |
None |
ContentLength |
Int |
Sets the length of the request content |
None |
ContentType |
String |
Content type. Sets Content-Type . |
None |
Metadata |
Array |
User-defined file metadata |
None |
Restore |
String |
Restoration information of the archived file |
None |
Copying an object
This API is used to copy an object to the destination path.
Method prototype
public Guzzle\Service\Resource\Model copyObject(array $args = array());
Sample request
Sample 1. Copying an object
try {
$result = $cosClient->copyObject(array(
'Bucket' => 'examplebucket-1250000000',
'Key' => 'exampleobject',
'CopySource' => 'sourcebucket-1250000000.cos.ap-guangzhou.myqcloud.com/sourceObject',
));
print_r($result);
} catch (\Exception $e) {
echo($e);
}
Sample 2. Copying an object with specified version ID
try {
$result = $cosClient->copyObject(array(
'Bucket' => 'examplebucket-1250000000',
'Key' => 'exampleobject',
'CopySource' => 'sourcebucket-1250000000.cos.ap-guangzhou.myqcloud.com/sourceObject?versionId=MTg0NDUxNjI3NTM0ODE2Njc0MzU',
));
print_r($result);
} catch (\Exception $e) {
echo($e);
}
Sample 3. Changing the storage class to ARCHIVE
try {
$result = $cosClient->copyObject(array(
'Bucket' => 'examplebucket-1250000000',
'Key' => 'exampleobject',
'CopySource' => 'sourcebucket-1250000000.cos.ap-guangzhou.myqcloud.com/sourceObject',
'StorageClass' => 'Archive'
));
print_r($result);
} catch (\Exception $e) {
echo($e);
}
try {
$result = $cosClient->copyObject(array(
'Bucket' => 'examplebucket-1250000000',
'Key' => 'exampleobject',
'CopySource' => 'sourcebucket-1250000000.cos.ap-guangzhou.myqcloud.com/sourceObject',
'MetadataDirective' => 'Replaced',
'Metadata' => array(
'key1' => 'value1',
'key2' => 'value2',
)
));
print_r($result);
} catch (\Exception $e) {
echo($e);
}
Parameter description
Parameter Name |
Type |
Description |
Required |
Bucket |
String |
Bucket name in the format: BucketName-APPID |
Yes |
Key |
String |
Uniquely identifies an object in a bucket. For example, if the object access endpoint is
examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg , its object key is doc/pic.jpg . |
Yes |
CopySource |
String |
Describes the path to the source object, including APPID , Bucket , Key , and Region , for example, examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg |
Yes |
MetadataDirective |
String |
Valid values: 'Copy': ignore the configured metadata and copy the file directly; 'Replaced': modify the metadata according to the configured metadata. If the destination path is identical to the source path, this parameter must be set to ‘Replaced’. |
No |
Deleting a single object
API description
This API is used to delete a specified object (file/object) from a bucket.
Method prototype
public Guzzle\Service\Resource\Model deleteObject(array $args = array());
Sample request
try {
$result = $cosClient->deleteObject(array(
'Bucket' => 'examplebucket-1250000000',
'Key' => 'exampleobject',
'VersionId' => 'exampleVersionId'
));
print_r($result);
} catch (\Exception $e) {
echo($e);
}
Parameter description
Parameter Name |
Type |
Description |
Required |
Bucket |
String |
Bucket name in the format: BucketName-APPID |
Yes |
Key |
String |
Uniquely identifies an object in a bucket. For example, if the object access endpoint is
examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg , its object key is doc/pic.jpg . |
Yes |
VersionId |
String |
Version ID of the deleted file |
No |
Deleting multiple objects
API description
This API is used delete multiple objects from a specified bucket in a single request.
Method prototype
public Guzzle\Service\Resource\Model deleteObjects(array $args = array());
Sample request
try {
$result = $cosClient->deleteObjects(array(
'Bucket' => 'examplebucket-1250000000',
'Objects' => array(
array(
'Key' => 'exampleobject',
'VersionId' => 'string'
),
),
));
print_r($result);
} catch (\Exception $e) {
echo($e);
}
Parameter description
Parameter Name |
Type |
Description |
Required |
Bucket |
String |
Bucket name in the format: BucketName-APPID |
Yes |
Objects |
Array |
List of deleted objects |
Yes |
Object |
Array |
Deleted object |
Yes |
Key |
String |
Uniquely identifies an object in a bucket. For example, if the object access endpoint is
examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg , its object key is doc/pic.jpg . |
Yes |
VersionId |
String |
Version ID of the deleted file |
No |
Response sample
Guzzle\Service\Resource\Model Object
(
[structure:protected] =>
[data:protected] => Array
(
[Deleted] => Array
(
[0] => Array
(
[Key] => exampleobject1
)
)
[Errors] => Array
(
[0] => Array
(
[Key] => exampleobject2
[Code] =>
[Message] =>
)
)
[RequestId] => NWNhZWYzYWNfMTlhYTk0MGFfNGRjX2MzZTVhOQ==
)
)
Response description
Parameter Name |
Type |
Description |
Parent Node |
Deleted |
Array |
List of successfully deleted objects |
None |
Errors |
Array |
List of objects that failed to be deleted |
None |
Key |
String |
Object key |
Deleted/Errors |
Code |
String |
Error code for failed operations |
Errors |
Message |
String |
Error message for failed operations |
Errors |
Restoring an archived object
API description
This (POST Object restore) API is used to restore an archived object for access.
Method prototype
public Guzzle\Service\Resource\Model restoreObject(array $args = array());
Sample request
try {
$result = $cosClient->restoreObject(array(
'Bucket' => 'examplebucket-1250000000',
'Key' => 'exampleobject',
'Days' => 10,
'CASJobParameters' => array(
'Tier' =>'Expedited'
)
));
print_r($result);
} catch (\Exception $e) {
echo($e);
}
Parameter description
Parameter Name |
Type |
Description |
Required |
Bucket |
String |
Bucket name in the format: BucketName-APPID |
Yes |
Key |
String |
Object key |
Yes |
Days |
String |
Sets the number of days before the temporary copy expires |
Yes |
CASJobParameters |
Array |
Restoration information |
Yes |
Tier |
String |
Specifies the restoration mode for archived data. For data in the ARCHIVE storage class, Tier can be set to Expedited , Standard , or Bulk . For data in DEEP ARCHIVE, Tier can be set to Standard or Bulk . |
Yes |
Multipart Operations
Operations related to multipart uploads are as follows:
- Uploading objects with multipart upload: initializing a multipart upload, uploading parts, and completing a multipart upload.
- Resuming a multipart upload: querying uploaded parts, uploading remaining parts, and completing a multipart upload.
- Deleting uploaded parts
Querying a multipart upload
API description
This API is used to query in-progress multipart uploads in a specified bucket.
Method prototype
public Guzzle\Service\Resource\Model listMultipartUploads(array $args = array());
Sample request
try {
$result = $cosClient->listMultipartUploads(array(
'Bucket' => 'examplebucket-1250000000',
'Delimiter' => '/',
'EncodingType' => 'url',
'KeyMarker' => 'prfixKeyMarker',
'UploadIdMarker' => 'string',
'Prefix' => 'prfix',
'MaxUploads' => 1000,
));
print_r($result);
} catch (\Exception $e) {
echo($e);
}
Parameter description
Parameter Name |
Type |
Description |
Required |
Bucket |
String |
Bucket name in the format: BucketName-APPID |
Yes |
Delimiter |
String |
A separator that is left empty by default. For example, you can set it to / to indicate folders. |
No |
EncodingType |
String |
Indicates the encoding method of the returned value. The value is not encoded by default. Valid value: url |
No |
KeyMarker |
String |
Marks the starting key of the list of returned parts |
No |
UploadIdMarker |
String |
Marks the starting upload ID of the list of returned parts |
No |
Prefix |
String |
Filters the object keys prefixed with the value of this parameter. It is left empty by default. |
No |
MaxUploads |
Int |
The maximum number of returned parts. Defaults to 1000 . |
No |
Response sample
Guzzle\Service\Resource\Model Object
(
[structure:protected] =>
[data:protected] => Array
(
[Bucket] => examplebucket-1250000000
[EncodingType] =>
[KeyMarker] =>
[UploadIdMarker] =>
[MaxUploads] => 1000
[Prefix] =>
[IsTruncated] =>
[Uploads] => Array
(
[0] => Array
(
[Key] => exampleobject
[UploadId] => 1551693693b1e6d0e00eec30c534059865ec89c9393028b60bfaf167e9420524b25eeb2940
[Initiator] => Array
(
[ID] => qcs::cam::uin/100000000001:uin/100000000001
[DisplayName] => 100000000001
)
[Owner] => Array
(
[ID] => qcs::cam::uin/100000000001:uin/100000000001
[DisplayName] => 100000000001
)
[StorageClass] => STANDARD
[Initiated] => 2019-03-04T10:01:33.000Z
)
[1] => Array
(
[Key] => exampleobject
[UploadId] => 155374001100563fe0e9d37964d53077e54e9d392bce78f630359cd3288e62acee2b719534
[Initiator] => Array
(
[ID] => qcs::cam::uin/100000000001:uin/100000000001
[DisplayName] => 100000000001
)
[Owner] => Array
(
[ID] => qcs::cam::uin/100000000001:uin/100000000001
[DisplayName] => 100000000001
)
[StorageClass] => STANDARD
[Initiated] => 2019-03-28T02:26:51.000Z
)
)
[RequestId] => NWNhNDJmNzBfZWFhZDM1MGFfMjYyM2FfMWIyNzhh
)
)
Response description
Parameter Name |
Type |
Description |
Parent Node |
Bucket |
String |
Bucket name in the format: BucketName-APPID |
None |
IsTruncated |
Int |
Indicates whether the returned objects are truncated |
None |
Uploads |
Array |
List of returned parts |
None |
Upload |
Array |
Attributes of the returned parts |
Uploads |
Key |
String |
Object key |
Upload |
UploadId |
String |
ID of the multipart upload |
Upload |
Initiator |
String |
Initiator of the multipart upload |
Upload |
Owner |
String |
Owner of the multipart upload |
Upload |
StorageClass |
String |
Storage class of the multipart upload |
Upload |
Initiated |
String |
Time the multipart upload was initiated |
Upload |
Initializing a multipart upload
API description
This API is used to initialize a multipart upload.
Method prototype
public Guzzle\Service\Resource\Model createMultipartUpload(array $args = array());
Sample request
try {
$result = $cosClient->createMultipartUpload(array(
'Bucket' => 'examplebucket-1250000000',
'Key' => 'exampleobject',
));
print_r($result);
} catch (\Exception $e) {
echo($e);
}
Parameter description
Parameter Name |
Type |
Description |
Required |
Bucket |
String |
Bucket name in the format: BucketName-APPID |
Yes |
Key |
String |
Uniquely identifies an object in a bucket. For example, if the object access endpoint is
examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg , its object key is doc/pic.jpg . |
Yes |
CacheControl |
String |
Cache policy. Sets Cache-Control . |
No |
ContentDisposition |
String |
File name. Sets Content-Disposition . |
No |
ContentEncoding |
String |
Encoding format. Sets Content-Encoding |
No |
ContentLanguage |
String |
Language type. Sets Content-Language |
No |
ContentLength |
Int |
Sets the length of the request content |
No |
ContentType |
String |
Content type. Sets Content-Type . |
No |
Expires |
String |
Sets Content-Expires . |
No |
Metadata |
Array |
User-defined file metadata |
No |
StorageClass |
String |
Storage class of the object, such as STANDARD (default), STANDARD_IA, and ARCHIVE. For more information, please see Storage Class Overview. |
No |
ContentMD5 |
String |
Sets the MD5 checksum of the uploaded file |
No |
ServerSideEncryption |
String |
Server-side encryption method |
No |
Sample response
Guzzle\Service\Resource\Model Object
(
[structure:protected] =>
[data:protected] => Array
(
[Bucket] => examplebucket-1250000000
[Key] => exampleobject
[UploadId] => 1554277569b3e83df05c730104c325eb7b56000449fb7d51300b0728aacde02a6ea7f6c033
[RequestId] => NWNhNDY0YzFfMmZiNTM1MGFfNTM2YV8xYjliMTg=
)
)
Response description
Parameter Name |
Type |
Description |
Parent Node |
Bucket |
String |
Bucket name in the format: BucketName-APPID |
None |
Key |
String |
Object key |
None |
UploadId |
String |
ID of the multipart upload |
None |
Uploading a part
This API is used to upload parts.
Method prototype
public Guzzle\Service\Resource\Model uploadPart(array $args = array());
Sample request
try {
$result = $cosClient->uploadPart(array(
'Bucket' => 'examplebucket-1250000000',
'Key' => 'exampleobject',
'Body' => 'string',
'UploadId' => 'exampleUploadId',
'PartNumber' => 1,
));
print_r($result);
} catch (\Exception $e) {
echo($e);
}
Parameter description
Parameter Name |
Type |
Description |
Required |
Bucket |
String |
Bucket name in the format: BucketName-APPID |
Yes |
Key |
String |
Object key |
Yes |
UploadId |
String |
ID of the multipart upload. This value is returned in the response of the initialization of the multipart Upload |
Yes |
Body |
File/String |
Uploaded content |
Yes |
PartNumber |
Int |
Part number; COS will merge parts based on part number |
Yes |
ContentLength |
Int |
Sets the length of the request content |
No |
ContentMD5 |
String |
Sets the MD5 checksum of the uploaded file |
No |
Response sample
Guzzle\Service\Resource\Model Object
(
[structure:protected] =>
[data:protected] => Array
(
[ETag] => "96e79218965eb72c92a549dd5a330112"
[RequestId] => NWNhNDdjYWFfNjNhYjM1MGFfMjk2NF8xY2ViMWM=
)
)
Response description
Parameter Name |
Type |
Description |
Parent Node |
ETag |
String |
MD5 checksum of the part |
None |
Copying parts
API description
This API is used to copy an object as a part.
Method prototype
public Guzzle\Service\Resource\Model uploadPartCopy(array $args = array());
Sample request
try {
$result = $cosClient->uploadPartCopy(array(
'Bucket' => 'examplebucket-1250000000',
'Key' => 'exampleobject',
'CopySource' => 'sourcebucket-1250000000.cos.ap-guangzhou.myqcloud.com/sourceObject',
'CopySourceRange' => 'bytes=0-1',
'UploadId' => 'exampleUploadId',
'PartNumber' => 1,
));
print_r($result);
} catch (\Exception $e) {
echo($e);
}
Parameter description
Parameter Name |
Type |
Description |
Required |
Bucket |
String |
Bucket name in the format: BucketName-APPID |
Yes |
Key |
String |
Object key |
Yes |
UploadId |
String |
ID of the multipart upload. This value is returned in the response of the initialization of the multipart Upload |
Yes |
CopySource |
String |
Describes the path to the source object, including APPID , Bucket , Key , and Region , for example, examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg |
Yes |
CopySourceRange |
String |
Describes the byte range of the source object to copy in the format: bytes=first-last . If no range is specified, the entire source object will be copied. |
No |
PartNumber |
Int |
Part number; COS will merge parts based on part number |
Yes |
ContentLength |
Int |
Sets the length of the request content |
No |
ContentMD5 |
String |
Sets the MD5 checksum of the uploaded file |
No |
Response sample
Guzzle\Service\Resource\Model Object
(
[structure:protected] =>
[data:protected] => Array
(
[ETag] => "96e79218965eb72c92a549dd5a330112"
[LastModified] => "2017-09-04T04:45:45"
[RequestId] => NWNhNDdjYWFfNjNhYjM1MGFfMjk2NF8xY2ViMWM=
)
)
Response description
Parameter Name |
Type |
Description |
Parent Node |
ETag |
String |
MD5 checksum of the part |
None |
LastModified |
String |
Returns the date/time the object was last modified in GMT format |
None |
Querying uploaded parts
API description
This API (List Parts) is used to query the uploaded parts of a multipart upload.
Method prototype
public Guzzle\Service\Resource\Model listParts(array $args = array());
Sample request
try {
$result = $cosClient->listParts(array(
'Bucket' => 'examplebucket-1250000000',
'Key' => 'exampleobject',
'UploadId' => 'exampleUploadId',
'PartNumberMarker' => 1,
'MaxParts' => 1000,
));
print_r($result);
} catch (\Exception $e) {
echo($e);
}
Parameter description
Parameter Name |
Type |
Description |
Required |
Bucket |
String |
Bucket name in the format: BucketName-APPID |
Yes |
Key |
String |
Object key |
Yes |
UploadId |
String |
ID of the multipart upload |
Yes |
PartNumberMarker |
Int |
Marks the starting part of the list of returned parts |
No |
MaxParts |
Int |
The maximum number of returned parts; the default value is 1,000. |
No |
Response sample
Guzzle\Service\Resource\Model Object
(
[structure:protected] =>
[data:protected] => Array
(
[Bucket] => examplebucket-1250000000
[Key] => exampleobject
[UploadId] => 1554279643cf19d71bb5fb0d29613e5541131f3a96387d9e168cd939c23a3d608c9eb94707
[Owner] => Array
(
[ID] => 1250000000
[DisplayName] => 1250000000
)
[PartNumberMarker] => 1
[Initiator] => Array
(
[ID] => qcs::cam::uin/100000000001:uin/100000000001
[DisplayName] => 100000000001
)
[StorageClass] => Standard
[MaxParts] => 1000
[IsTruncated] =>
[Parts] => Array
(
[0] => Array
(
[PartNumber] => 2
[LastModified] => 2019-04-03T08:21:28.000Z
[ETag] => "b948e77469189ac94b98e09755a6dba9"
[Size] => 1048576
)
[1] => Array
(
[PartNumber] => 3
[LastModified] => 2019-04-03T08:21:22.000Z
[ETag] => "9e5060e2994ec8463bfbebd442fdff16"
[Size] => 1048576
)
)
[RequestId] => NWNhNDZkNTJfOGNiMjM1MGFfMTRlYl8xYmJiOTU=
)
)
Response description
Parameter Name |
Type |
Description |
Parent Node |
Bucket |
String |
Bucket name in the format: BucketName-APPID |
None |
Key |
String |
Object key |
None |
UploadId |
String |
ID of the multipart upload |
None |
IsTruncated |
Int |
Indicates whether the returned objects are truncated |
None |
PartNumberMarker |
Int |
Marks the starting part of the list of returned parts |
None |
MaxParts |
Int |
The maximum number of returned parts; the default value is 1,000. |
None |
Initiator |
String |
Initiator of the multipart upload |
None |
Parts |
Array |
List of returned parts |
None |
Part |
Array |
Attributes of the returned parts |
Parts |
PartNumber |
Int |
Part number which serves to identify the part |
Part |
LastModified |
String |
Date/time the part was last modified/time |
Part |
ETag |
String |
MD5 checksum of the part |
Part |
Size |
String |
Size of the part |
Part |
Completing a multipart upload
API description
This 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',
'Key' => 'exampleobject',
'UploadId' => 'exampleUploadId',
'Parts' => array(
array(
'ETag' => 'exampleETag',
'PartNumber' => 1,
)),
));
print_r($result);
} catch (\Exception $e) {
echo($e);
}
Parameter description
Parameter Name |
Type |
Description |
Required |
Bucket |
String |
Bucket name in the format: BucketName-APPID |
Yes |
Key |
String |
Object key |
Yes |
UploadId |
String |
ID of the multipart upload |
Yes |
Parts |
Array |
List of parts |
Yes |
Part |
Array |
Information on the uploaded parts |
Yes |
ETag |
String |
MD5 checksum of the part |
Yes |
PartNumber |
Int |
Part number which serves to identify the part |
Yes |
Aborting a multipart upload
API description
This API is used to abort a multipart upload and delete the uploaded parts.
Method prototype
public Guzzle\Service\Resource\Model abortMultipartUpload(array $args = array());
Sample request
try {
$result = $cosClient->abortMultipartUpload(array(
'Bucket' => 'examplebucket-1250000000',
'Key' => 'exampleobject',
'UploadId' => 'exampleUploadId',
));
print_r($result);
} catch (\Exception $e) {
echo($e);
}
Parameter description
Parameter Name |
Type |
Description |
Required |
Bucket |
String |
Bucket name in the format: BucketName-APPID |
Yes |
Key |
String |
Object key |
Yes |
UploadId |
String |
ID of the multipart upload |
Yes |
Advanced APIs (recommended)
This section encapsulates advanced APIs for uploading and copying. You only need to set the corresponding parameters. The APIs will decide internally whether to perform simple upload/copy or multipart upload/copy based on the file size. Before using the APIs, make sure you have completed the initialization as instructed in Getting Started.
Uploading an object
API description
This API is used to call the simple upload API for small files, and the multipart upload API for large files. For the API parameters, please see those of the PUT Object
and Upload Part
APIs.
Sample request
Sample 1. Uploading an object
try {
$result = $cosClient->Upload(
$bucket = 'examplebucket-1250000000',
$key = 'exampleobject',
$body = fopen('path/to/localFile', 'rb')
);
print_r($result);
} catch (\Exception $e) {
echo($e);
}
Sample 2. Uploading an archived object
try {
$result = $cosClient->Upload(
$bucket = 'examplebucket-1250000000',
$key = 'exampleobject',
$body = fopen('path/to/localFile', 'rb'),
$options = array(
'StorageClass' => 'Archive'
)
);
print_r($result);
} catch (\Exception $e) {
echo($e);
}
try {
$result = $cosClient->Upload(
$bucket = 'examplebucket-1250000000',
$key = 'exampleobject',
$body = fopen('path/to/localFile', 'rb'),
$options = array(
'Metadata' => array(
'string' => 'string',
),
'PartSize' => 10 * 1024 * 1024
)
);
print_r($result);
} catch (\Exception $e) {
echo($e);
}
Object replication
API description
This API is used to call the copy object API for small files, and the multipart copy API for large files. For the API parameters, please see those of the PUT Object - Copy
and Upload Part - Copy
APIs.
Sample request
Sample 1. Copying an object
try {
$result = $cosClient->Copy(
$bucket = 'examplebucket-1250000000',
$key = 'exampleobject',
$copySorce = array(
'Region' => 'COS_REGION',
'Bucket' => 'sourcebucket-1250000000',
'Key' => 'sourceobject',
)
);
print_r($result);
} catch (\Exception $e) {
echo($e);
}
Sample 2. Transitioning an object between COS storage classes
try {
$result = $cosClient->Copy(
$bucket = 'examplebucket-1250000000',
$key = 'exampleobject',
$copySorce = array(
'Region' => 'COS_REGION',
'Bucket' => 'examplebucket-1250000000',
'Key' => 'exampleobject',
),
$options = array(
'StorageClass' => 'Archive'
)
);
print_r($result);
} catch (\Exception $e) {
echo($e);
}
Sample 3. Modify object storage attributes
try {
$result = $cosClient->Copy(
$bucket = 'examplebucket-1250000000',
$key = 'exampleobject',
$copySorce = array(
'Region' => 'COS_REGION',
'Bucket' => 'sourcebucket-1250000000',
'Key' => 'sourceObject',
),
$options = array(
'MetadataDirective' => 'Replaced',
'Metadata' => array(
'string' => 'string',
),
)
);
print_r($result);
} catch (\Exception $e) {
echo($e);
}
Was this page helpful?