存储桶操作

简介

本文档提供关于存储桶的基本操作和访问控制列表（ACL）的相关 API 概览以及 SDK 示例代码。

基本操作

访问控制列表（ACL）

基本操作

创建存储桶

功能说明

在指定账号下创建一个存储桶（PUT Bucket）。

方法原型

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

请求示例

try {
    $result = $cosClient->createBucket(array(
        'Bucket' => 'examplebucket-1250000000' //格式：BucketName-APPID
    )); 
    // 请求成功
    print_r($result);
} catch (\Exception $e) {
    // 请求失败
    echo($e);
}

参数说明

检索存储桶及其权限

功能说明

确认 Bucket 是否存在且是否有权限访问（HEAD Bucket）。

方法原型

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

请求示例

try {
    $result = $cosClient->headBucket(array(
        'Bucket' => 'examplebucket-1250000000' //格式：BucketName-APPID
    )); 
    // 请求成功
    print_r($result);
} catch (\Exception $e) {
    // 请求失败
    echo($e);
}

参数说明

删除存储桶

功能说明

删除指定账号下的空存储桶。

方法原型

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

请求示例

try {
    $result = $cosClient->deleteBucket(array(
        'Bucket' => 'examplebucket-1250000000' //格式：BucketName-APPID
    )); 
    // 请求成功
    print_r($result);
} catch (\Exception $e) {
    // 请求失败
    echo($e);
}

参数说明

访问控制列表

设置存储桶 ACL

功能说明

设置指定存储桶的访问权限控制列表（ACL）。

方法原型

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

请求示例

try {
    $result = $cosClient->putBucketAcl(array(
        'Bucket' => 'examplebucket-1250000000', //格式：BucketName-APPID
        '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',
        )));
    // 请求成功
    print_r($result);
} catch (\Exception $e) {
    // 请求失败
    echo "$e\n";
}

参数说明

查询存储桶 ACL

功能说明

获取指定存储桶的访问权限控制列表（ACL）。

方法原型

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

请求示例

try {
    $result = $cosClient->getBucketAcl(array(
        'Bucket' => 'examplebucket-1250000000' //格式：BucketName-APPID
    )); 
    // 请求成功
    print_r($result);
} catch (\Exception $e) {
    // 请求失败
    echo($e);
}

返回结果示例

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

返回结果说明

对象操作

简介

本文档提供关于对象的简单操作、分块操作等其他操作相关的 API 概览以及 SDK 示例代码。

简单操作

分块操作

其他操作

简单操作

查询对象列表

功能说明

查询指定存储桶中所有的对象（List Object）。

方法原型

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

请求示例

try {
    $result = $cosClient->listObjects(array(
        'Bucket' => 'examplebucket-1250000000', //格式：BucketName-APPID
        'Delimiter' => '/',
        'EncodingType' => 'url',
        'Marker' => 'doc/picture.jpg',
        'Prefix' => 'doc',
        'MaxKeys' => 1000,
    )); 
    // 请求成功
    print_r($result);
} catch (\Exception $e) {
    // 请求失败
    echo($e);
}

参数说明

返回结果示例

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

)

返回结果说明

查询对象及其历史版本列表

功能说明

查询存储桶下的部分或者全部对象及其历史版本信息。

方法原型

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

请求示例

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

参数说明

返回结果示例

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
        )

)

返回结果说明

简单上传对象

功能说明

上传对象到指定的存储桶中（PUT Object），最大支持5G大小的文件，如果需要上传超过5G的文件，建议使用高级接口中的复合上传接口。

方法原型

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

请求示例

try { 
    $result = $cosClient->putObject(array( 
        'Bucket' => 'examplebucket-1250000000', //格式：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'
        */
    )); 
    // 请求成功 
    print_r($result); 
} catch (\Exception $e) { 
    // 请求失败 
    echo($e); 
}

参数说明

返回结果示例

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
        )

)

返回结果说明

查询对象元数据

功能说明

查询 Object 的 Meta 信息（HEAD Object）。

方法原型

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

请求示例

$cosClient = new Qcloud\Cos\Client(
    array(
        'schema' => 'http',       // 协议头部，默认为http
        'region' => $region,      // Region
        'endpoint' => $endpoint,  // Endpoint
        'credentials'=> array(
            'secretId'  => $secretId ,
            'secretKey' => $secretKey)));
try {
    $result = $cosClient->headObject(array(
        'Bucket' => 'examplebucket-1250000000', //格式：BucketName-APPID
        'Key' => 'exampleobject',
    )); 
    // 请求成功
    print_r($result);
} catch (\Exception $e) {
    // 请求失败
    echo($e);
}

参数说明

返回结果示例

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

)

返回结果说明

下载对象

功能说明

下载对象到本地（GET Object）。

方法原型

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

请求示例

try {
    $result = $cosClient->getObject(array(
        'Bucket' => 'examplebucket-1250000000', //格式：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',
        */
    )); 
    // 请求成功
    print_r($result);
} catch (\Exception $e) {
    // 请求失败
    echo($e);
}

参数说明

返回结果示例

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
        )

)

返回结果说明

设置对象复制

将一个对象复制到目标路径（PUT Object - Copy）。

方法原型

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

请求示例

try {
    $result = $cosClient->copyObject(array(
        'Bucket' => 'examplebucket-1250000000', //格式：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'
        */
    )); 
    // 请求成功
    print_r($result);
} catch (\Exception $e) {
    // 请求失败
    echo($e);
}

参数说明

删除单个对象

功能说明

在存储桶中删除指定 Object （文件/对象）。

方法原型

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

请求示例

try {
    $result = $cosClient->deleteObject(array(
        'Bucket' => 'examplebucket-1250000000', //格式：BucketName-APPID
        'Key' => 'exampleobject',
        'VersionId' => 'string'
    )); 
    // 请求成功
    print_r($result);
} catch (\Exception $e) {
    // 请求失败
    echo($e);
}

参数说明

删除多个对象

功能说明

在存储桶中批量删除 Object （文件/对象）。

方法原型

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

请求示例

try {
    $result = $cosClient->deleteObjects(array(
        'Bucket' => 'examplebucket-1250000000', //格式：BucketName-APPID
        'Objects' => array(
            array(
                'Key' => 'exampleobject',
                'VersionId' => 'string'
            ),  
            // ... repeated
        ),  
    )); 
    // 请求成功
    print_r($result);
} catch (\Exception $e) {
    // 请求失败
    echo($e);
}

参数说明

返回结果示例

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

返回结果说明

分块操作

查询分片上传

功能说明

查询指定存储桶中正在进行的分片上传（List Multipart Uploads）。

方法原型

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

请求示例

try {
    $result = $cosClient->listMultipartUploads(array(
        'Bucket' => 'examplebucket-1250000000', //格式：BucketName-APPID
        'Delimiter' => '/',
        'EncodingType' => 'url',
        'KeyMarker' => 'string',
        'UploadIdMarker' => 'string',
        'Prefix' => 'prfix',
        'MaxUploads' => 1000,
    )); 
    // 请求成功
    print_r($result);
} catch (\Exception $e) {
    // 请求失败
    echo($e);
}

参数说明

返回结果示例

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
        )

)

返回结果说明

分片上传对象

分片上传对象可包括的操作：

• 分片上传对象： 初始化分片上传， 上传分片块， 完成分块上传。
• 分片续传：查询已上传块， 上传分片块，完成分块上传。
• 删除已上传分片块。

初始化分片上传

功能说明

初始化 Multipart Upload 上传操作（Initiate Multipart Upload）。

方法原型

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

请求示例

try {
    $result = $cosClient->createMultipartUpload(array(
        'Bucket' => 'examplebucket-1250000000', //格式：BucketName-APPID
        'Key' => 'exampleobject',
        /*  
        'CacheControl' => 'string',
        'ContentDisposition' => 'string',
        'ContentEncoding' => 'string',
        'ContentLanguage' => 'string',
        'ContentLength' => integer,
        'ContentType' => 'string',
        'Expires' => 'string',
        'Metadata' => array(
            'string' => 'string',
        ),
        'StorageClass' => 'string'
        */
    )); 
    // 请求成功
    print_r($result);
} catch (\Exception $e) {
    // 请求失败
    echo($e);
}

参数说明

返回结果示例

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

)

返回结果说明

查询已上传块

功能说明

查询特定分块上传操作中的已上传的块（List Parts）。

方法原型

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

请求示例

try {
    $result = $cosClient->listParts(array(
        'Bucket' => 'examplebucket-1250000000', //格式：BucketName-APPID
        'Key' => 'exampleobject',
        'UploadId' => 'NWNhNDY0YzFfMmZiNTM1MGFfNTM2YV8xYjliMTg',
        'PartNumberMarker' => 1,
        'MaxParts' => 1000,
    )); 
    // 请求成功
    print_r($result);
} catch (\Exception $e) {
    // 请求失败
    echo($e);
}

参数说明

返回结果示例

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

)

返回结果说明

上传分块

分块上传文件（Upload Part）。

方法原型

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

请求示例

try {
    $result = $cosClient->uploadPart(array(
        'Bucket' => 'examplebucket-1250000000', //格式：BucketName-APPID
        'Key' => 'exampleobject', 
        'Body' => 'string',
        'UploadId' => 'NWNhNDY0YzFfMmZiNTM1MGFfNTM2YV8xYjliMTg',
        'PartNumber' => integer,
        /*
        'ContentMD5' => 'string',
        'ContentLength' => integer,
        */
    )); 
    // 请求成功
    print_r($result);
} catch (\Exception $e) {
    // 请求失败
    echo($e);
}

参数说明

返回结果示例

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

)

返回结果说明

完成分块上传

功能说明

完成整个文件的分块上传（Complete Multipart Upload）。

方法原型

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

请求示例

try {
    $result = $cosClient->completeMultipartUpload(array(
        'Bucket' => 'examplebucket-1250000000', //格式：BucketName-APPID
        'Key' => 'exampleobject', 
        'UploadId' => 'string',
        'Parts' => array(
            array(
                'ETag' => 'string',
                'PartNumber' => integer,
            ),  
            array(
                'ETag' => 'string',
                'PartNumber' => integer,
            )), 
            // ... repeated
    )); 
    // 请求成功
    print_r($result);
} catch (\Exception $e) {
    // 请求失败
    echo($e);
}

参数说明

终止分块上传

功能说明

终止一个分块上传操作并删除已上传的块（Abort Multipart Upload）。

方法原型

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

请求示例

try {
    $result = $cosClient->abortMultipartUpload(array(
        'Bucket' => 'examplebucket-1250000000', //格式：BucketName-APPID
        'Key' => 'exampleobject', 
        'UploadId' => 'string',
    )); 
    // 请求成功
    print_r($result);
} catch (\Exception $e) {
    // 请求失败
    echo($e);
}

参数说明

其他操作

设置对象 ACL

功能说明

设置指定对象访问权限控制列表（ACL）（PUT Object acl）。

方法原型

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

请求示例

try {
    $result = $cosClient->putObjectAcl(array(
        'Bucket' => 'examplebucket-1250000000', //格式：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',
        )));
    // 请求成功
    print_r($result);
} catch (\Exception $e) {
    // 请求失败
    echo "$e\n";
}

参数说明

获取对象 ACL

功能说明

获取指定对象的访问权限控制列表（ACL）（GET Object acl）。

方法原型

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

请求示例

try {
    $result = $cosClient->getObjectAcl(array(
        'Bucket' => 'examplebucket-1250000000' //格式：BucketName-APPID
        'Key' => 'exampleobject',
    )); 
    // 请求成功
    print_r($result);
} catch (\Exception $e) {
    // 请求失败
    echo($e);
}

返回结果示例

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

返回结果说明

高级接口（推荐）

该小节主要讲述由 COS 提供的封装了上传和复制操作的高级接口，用户只需要设置相应的参数，该接口内部会根据文件大小决定是进行简单上传（复制）还是分片上传（复制），使用接口前请确认已完成了 快速入门 中指引的初始化步骤。

复合上传

功能说明

该接口内部会根据文件大小，对小文件调用简单上传接口，对大文件调用分块上传接口。

请求示例

try {
    $result = $cosClient->Upload(
        $bucket = 'examplebucket-1250000000', //格式：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'
        )
        */
    );
    // 请求成功
    print_r($result);
} catch (\Exception $e) {
    // 请求失败
    echo($e);
}

复合复制

功能说明

该接口内部会根据文件大小，对小文件调用设置对象复制接口，对大文件调用分块复制接口。

请求示例

try {
    $result = $cosClient->Copy(
        $bucket = 'examplebucket-1250000000', //格式：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'
        )
        */
    );
    // 请求成功
    print_r($result);
} catch (\Exception $e) {
    // 请求失败
    echo($e);
}

存储桶管理

简介

本文档提供关于跨域访问、生命周期、版本控制、跨地域复制相关的 API 概览以及 SDK 示例代码。

跨域访问

版本控制

跨地域复制

跨域访问

设置跨域配置

功能说明

设置指定存储桶的跨域名访问配置信息（PUT Bucket cors）。

方法原型

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

请求示例

try {
    $result = $cosClient->putBucketCors(array(
        'Bucket' => 'examplebucket-1250000000', //格式：BucketName-APPID
        'CORSRules' => array(
            array(
                'AllowedHeaders' => array('*',),
                'AllowedMethods' => array('Put', ),
                'AllowedOrigins' => array('*', ),
                'ExposeHeaders' => array('*', ),
                'MaxAgeSeconds' => 1,
            ),  
            // ... repeated
        )   
    )); 
    // 请求成功
    print_r($result);
} catch (\Exception $e) {
    // 请求失败
    echo "$e\n";
}

参数说明

查询跨域配置

功能说明

查询指定存储桶的跨域名访问配置信息（GET Bucket cors）。

方法原型

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

请求示例

try {
    $result = $cosClient->getBucketCors(array(
        'Bucket' => 'examplebucket-1250000000' //格式：BucketName-APPID
    )); 
    // 请求成功
    print_r($result);
} catch (\Exception $e) {
    // 请求失败
    echo($e);
}

参数说明

返回结果示例

Guzzle\Service\Resource\Model Object
(
    [data:protected] => Array
        (
            [CORSRules] => Array
                (
                    [0] => Array
                        (
                            [ID] => 1234
                            [AllowedHeaders] => Array
                                (
                                    [0] => *
                                )
                            [AllowedMethods] => Array
                                (
                                    [0] => PUT
                                )
                            [AllowedOrigins] => Array
                                (
                                    [0] => http://www.qq.com
                                )
                        )
                )
            [RequestId] => NWE3YzhkMmRfMTdiMjk0MGFfNTQzZl8xNWUwMGU=
        )
)

返回结果说明

删除跨域配置

功能说明

删除指定存储桶的跨域名访问配置（DELETE Bucket cors）。

方法原型

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

请求示例

try {
    $result = $cosClient->deleteBucketCors(array(
        'Bucket' => 'examplebucket-1250000000' //格式：BucketName-APPID
    )); 
    // 请求成功
    print_r($result);
} catch (\Exception $e) {
    // 请求失败
    echo($e);
}

参数说明

版本控制

设置版本控制

功能说明

设置指定存储桶的版本控制功能（PUT Bucket versioning）。

方法原型

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

请求示例

开启版本控制

try {
    $result = $cosClient->putBucketVersioning(array(
        'Bucket' => 'examplebucket-125000000', //格式：BucketName-APPID
        'Status' => 'Enabled'
    )); 
    // 请求成功
    print_r($result);
} catch (\Exception $e) {
    // 请求失败
    echo "$e\n";
}

暂停版本控制

try {
    $result = $cosClient->putBucketVersioning(array(
        'Bucket' => 'examplebucket-125000000', //格式：BucketName-APPID
        'Status' => 'Suspended'
    )); 
    // 请求成功
    print_r($result);
} catch (\Exception $e) {
    // 请求失败
    echo "$e\n";
}

参数说明

查询版本控制

功能说明

查询指定存储桶的版本控制信息（GET Bucket versioning）。

方法原型

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

请求示例

try {
    $result = $cosClient->getBucketVersioning(array(
        'Bucket' => 'examplebucket-125000000', //格式：BucketName-APPID
    )); 
    // 请求成功
    print_r($result);
} catch (\Exception $e) {
    // 请求失败
    echo "$e\n";
}

参数说明

返回结果说明

跨地域复制

设置跨地域复制

功能说明

设置指定存储桶的跨地域复制规则（PUT Bucket replication）。

方法原型

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

请求示例

try {
    $result = $cosClient->putBucketReplication(array(
        'Bucket' => 'examplebucket-125000000', //格式：BucketName-APPID
        'Role' => 'qcs::cam::uin/100000000001:uin/100000000001',
        'Rules'=>array(
            array(
                'Status' => 'Enabled',
                'ID' => 'string',
                'Prefix' => 'string',
                'Destination' => array(                    'Bucket' => 'qcs::cos:ap-guangzhou::examplebucket2-125000000',
                    'StorageClass' => 'standard',                ),  
                // ...repeated            ),  
        ),      )); 
    // 请求成功    print_r($result);
} catch (\Exception $e) {    // 请求失败
    echo "$e\n";
}

参数说明

查询跨地域复制

功能说明

查询指定存储桶的跨地域复制规则（GET Bucket replication）。

方法原型

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

请求示例

try {
    $result = $cosClient->getBucketReplication(array(
        'Bucket' => 'examplebucket-125000000', //格式：BucketName-APPID
    )); 
    // 请求成功
    print_r($result);
} catch (\Exception $e) {
    // 请求失败
    echo "$e\n";
}

参数说明

返回结果示例

Guzzle\Service\Resource\Model Object
(
    [data:protected] => Array
        (
            [Role] => qcs::cam::uin/100000000001:uin/100000000001
            [Rules] => Array
                (
                    [0] => Array
                        (
                            [ID] => string
                            [Status] => Enabled
                            [Prefix] => string
                            [Destination] => Array
                                (
                                    [Bucket] => qcs::cos:ap-guangzhou::examplebucket2-125000000
                                    [StorageClass] => 
                                )
                        )
                )
            [RequestId] => NWQwOGI5MGVfNWFiMjU4NjRfNDUzY19mNzRhMTU=
        )
)

返回结果说明

删除跨地域复制

功能说明

删除指定存储桶的跨地域复制规则（DELETE Bucket replication）。

方法原型

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

请求示例

try {
    $result = $cosClient->deleteBucketReplication(array(
        'Bucket' => 'examplebucket-125000000', //格式：BucketName-APPID
    )); 
    // 请求成功
    print_r($result);
} catch (\Exception $e) {
    // 请求失败
    echo "$e\n";
}

参数说明

预签名 URL

简介

PHP SDK 提供获取请求预签名 URL 接口。

永久密钥预签名请求示例

上传请求示例

$secretId = "COS_SECRETID";                  // 替换为用户的 SecretId
$secretKey = "COS_SECRETKEY";                // 替换为用户的 SecretKey

$region = "REGION";                          // 替换为用户的 Region
$domain = "DOMAIN.COM";                      // 替换为用户的 Domain

$formatRegion = sprintf("cos.%s", $region);  // 格式化为标准的 Region (前方加 cos.)
$endpoint = sprintf("%s.%s", $formatRegion, $domain);
                                             // 通过 FormatRegion 和 Domain 生成 Endpoint

$cosClient = new Qcloud\Cos\Client(
    array(
        'schema' => 'http',       // 协议头部，默认为http
        'region' => $region,      // Region
        'endpoint' => $endpoint,  // Endpoint
        'credentials'=> array(
            'secretId'  => $secretId ,
            'secretKey' => $secretKey)));

### 简单上传预签名
try {
    $command = $cosClient->getCommand('putObject', array(
        'Bucket' => "examplebucket-1250000000", //存储桶，格式：BucketName-APPID
        'Key' => "exampleobject", //对象在存储桶中的位置，即对象键
        'Body' => '', //
    ));
    $signedUrl = $command->createPresignedUrl('+10 minutes');
    // 请求成功
    echo ($signedUrl);
} catch (\Exception $e) {
    // 请求失败
    echo($e);
}

### 分块上传预签名
try {
    $command = $cosClient->getCommand('uploadPart', array(
        'Bucket' => "examplebucket-1250000000", //存储桶，格式：BucketName-APPID
        'Key' => "exampleobject", //对象在存储桶中的位置，即对象键
        'UploadId' => '',
        'PartNumber' => '1',
        'Body' => '', 
    ));
    $signedUrl = $command->createPresignedUrl('+10 minutes');
    // 请求成功
    echo ($signedUrl);
} catch (\Exception $e) {
    // 请求失败
    echo($e);
}

下载请求示例

$secretId = "COS_SECRETID";                  // 替换为用户的 SecretId
$secretKey = "COS_SECRETKEY";                // 替换为用户的 SecretKey

$region = "REGION";                          // 替换为用户的 Region
$domain = "DOMAIN.COM";                      // 替换为用户的 Domain

$formatRegion = sprintf("cos.%s", $region);  // 格式化为标准的 Region (前方加 cos.)
$endpoint = sprintf("%s.%s", $formatRegion, $domain);
                                             // 通过 FormatRegion 和 Domain 生成 Endpoint

$cosClient = new Qcloud\Cos\Client(
    array(
        'schema' => 'http',       // 协议头部，默认为http
        'region' => $region,      // Region
        'endpoint' => $endpoint,  // Endpoint
        'credentials'=> array(
            'secretId'  => $secretId ,
            'secretKey' => $secretKey)));

### 简单下载预签名
try {
    $command = $cosClient->getCommand('getObject', array(
        'Bucket' => "examplebucket-1250000000", //存储桶，格式：BucketName-APPID
        'Key' => "exampleobject" //对象在存储桶中的位置，即对象键
    ));
    $signedUrl = $command->createPresignedUrl('+10 minutes');
    // 请求成功
    echo ($signedUrl);
} catch (\Exception $e) {
    // 请求失败
    echo($e);
}

### 使用封装的 getObjectUrl 获取下载签名
try {    
    $bucket = "examplebucket-1250000000"; //存储桶，格式：BucketName-APPID
    $key = "exampleobject"; //对象在存储桶中的位置，即对象键
    $signedUrl = $cosClient->getObjectUrl($bucket, $key, '+10 minutes');
    // 请求成功
    echo $signedUrl;
} catch (\Exception $e) {
    // 请求失败
    print_r($e);
}

临时密钥预签名请求示例

上传请求示例

$secretId = "COS_SECRETID";                  // 临时密钥 SecretId
$secretKey = "COS_SECRETKEY";                // 临时密钥 SecretKey
$tmpToken = "COS_TMPTOKEN"                   // 临时密钥 Token

$region = "REGION";                          // 替换为用户的 Region
$domain = "DOMAIN.COM";                      // 替换为用户的 Domain

$formatRegion = sprintf("cos.%s", $region);  // 格式化为标准的 Region (前方加 cos.)
$endpoint = sprintf("%s.%s", $formatRegion, $domain);
                                             // 通过 FormatRegion 和 Domain 生成 Endpoint

$cosClient = new Qcloud\Cos\Client(
    array(
        'schema' => 'http',       // 协议头部，默认为http
        'region' => $region,      // Region
        'endpoint' => $endpoint,  // Endpoint
        'credentials'=> array(
            'secretId'  => $secretId ,
            'secretKey' => $secretKey,
            'token' => $tmpToken)));

### 简单上传预签名
try {
    $command = $cosClient->getCommand('putObject', array(
        'Bucket' => "examplebucket-1250000000", //存储桶，格式：BucketName-APPID
        'Key' => "exampleobject", //对象在存储桶中的位置，即对象键
        'Body' => '', 
    ));
    $signedUrl = $command->createPresignedUrl('+10 minutes');
    // 请求成功
    echo ($signedUrl);
} catch (\Exception $e) {
    // 请求失败
    echo($e);
}

### 分块上传预签名
try {
    $command = $cosClient->getCommand('uploadPart', array(
        'Bucket' => "examplebucket-1250000000", //存储桶，格式：BucketName-APPID
        'Key' => "exampleobject", //对象在存储桶中的位置，即对象键
        'UploadId' => '',
        'PartNumber' => '1',
        'Body' => '', 
    ));
    $signedUrl = $command->createPresignedUrl('+10 minutes');
    // 请求成功
    echo ($signedUrl);
} catch (\Exception $e) {
    // 请求失败
    echo($e);
}

下载请求示例

$secretId = "COS_SECRETID";                  // 临时密钥 SecretId
$secretKey = "COS_SECRETKEY";                // 临时密钥 SecretKey
$tmpToken = "COS_TMPTOKEN"                   // 临时密钥 Token

$region = "REGION";                          // 替换为用户的 Region
$domain = "DOMAIN.COM";                      // 替换为用户的 Domain

$formatRegion = sprintf("cos.%s", $region);  // 格式化为标准的 Region (前方加 cos.)
$endpoint = sprintf("%s.%s", $formatRegion, $domain);
                                             // 通过 FormatRegion 和 Domain 生成 Endpoint

$cosClient = new Qcloud\Cos\Client(
    array(
        'schema' => 'http',       // 协议头部，默认为http
        'region' => $region,      // Region
        'endpoint' => $endpoint,  // Endpoint
        'credentials'=> array(
            'secretId'  => $secretId ,
            'secretKey' => $secretKey,
            'token' => $tmpToken)));

### 简单下载预签名
try {
    $command = $cosClient->getCommand('getObject', array(
        'Bucket' => "examplebucket-1250000000", //存储桶，格式：BucketName-APPID
        'Key' => "exampleobject" //对象在存储桶中的位置，即对象键
    ));
    $signedUrl = $command->createPresignedUrl('+10 minutes');
    // 请求成功
    echo ($signedUrl);
} catch (\Exception $e) {
    // 请求失败
    echo($e);
}

### 使用封装的 getObjectUrl 获取下载签名
try {    
    $bucket = "examplebucket-1250000000"; //存储桶，格式：BucketName-APPID
    $key = "exampleobject"; //对象在存储桶中的位置，即对象键
    $signedUrl = $cosClient->getObjectUrl($bucket, $key, '+10 minutes');
    // 请求成功
    echo $signedUrl;
} catch (\Exception $e) {
    // 请求失败
    print_r($e);
}
​```

异常处理

简介

调用 SDK 接口请求 COS 服务失败时，如返回码为4xx或者5xx，系统将抛出 （Qcloud\Cos\Exception\ServiceResponseException）异常。

服务端异常

CosServerException 包含了服务端返回的状态码、requestid 和出错明细等。捕获异常后，建议对整个异常进行打印，异常包含了必须的排查因素。以下是异常成员变量的描述以及异常捕获示例：

异常捕获示例

try {
   $cosClient->listBuckets() 
} catch (\Exception $e) {
    $statusCode = $e->getStatusCode(); // 获取错误码
    $errorMessage = $e->getMessage(); // 获取错误信息
    $requestId = $e->getRequestId(); // 获取错误的 requestId
    $errorCode = $e->getCosErrorCode(); // 获取错误名称
    $request = $e->getRequest(); // 获取完整的请求
    $response = $e->getResponse(); // 获取完整的响应
｝