对象操作

最近更新时间:2019-04-18 17:05:50

简介

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

简单操作

API 操作名 操作描述
GET Bucket(List Object) 查询对象列表 查询存储桶下的部分或者全部对象
PUT Object 简单上传对象 上传一个 Object(文件/对象)至 Bucket
POST Object 表单上传对象 使用表单请求上传对象
HEAD Object 查询对象元数据 查询 Object 的 Meta 信息
GET Object 下载对象 下载一个 Object(文件/对象)至本地
PUT Object - Copy 设置对象复制 复制文件到目标路径
DELETE Object 删除单个对象 在 Bucket 中删除指定 Object (文件/对象)
DELETE Multiple Object 删除多个对象 在 Bucket 中批量删除 Object (文件/对象)

分块操作

API 操作名 操作描述
List Multipart Uploads 查询分块上传 查询正在进行中的分块上传信息
Initiate Multipart Upload 初始化分块上传 初始化 Multipart Upload 上传操作
Upload Part 上传分块 分块上传对象
Upload Part - Copy 复制分块 将其他对象复制为一个分块
List Parts 查询已上传块 查询特定分块上传操作中的已上传的块
Complete Multipart Upload 完成分块上传 完成整个对象的分块上传
Abort Multipart Upload 终止分块上传 终止一个分块上传操作并删除已上传的块

其他操作

API 操作名 操作描述
POST Object restore 恢复归档对象 将归档类型的对象取回访问
PUT Object acl 设置对象 ACL 设置 Bucket 中某个 Object (文件/对象)的 ACL
GET Object acl 查询对象 ACL 查询 Object(文件/对象)的 ACL

简单操作

查询对象列表

功能说明

查询指定存储桶中所有的对象(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);
}

参数说明

参数名称 类型 描述 父节点
Bucket String 存储桶名称,格式:BucketName-APPID
Delimiter String 默认为空,设置分隔符,比如设置/来模拟文件夹
EncodingType String 默认不编码,规定返回值的编码方式,可选值:url
Marker String 默认以 UTF-8 二进制顺序列出条目,标记返回 objects 的 list 的起点位置
Prefix String 默认为空,对 object 的 key 进行筛选,匹配指定前缀(prefix)的 objects
MaxKeys Int 最多返回的 objects 数量,默认为最大的1000

返回结果示例

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

)

返回结果说明

参数名称 类型 描述 父节点
Name String 存储桶名称,格式:BucketName-APPID
Delimiter String 设置分隔符,比如设置/来模拟文件夹
EncodingType String 规定返回值的编码方式
Marker String 默认以 UTF-8 二进制顺序列出条目,标记返回 objects 的 list 的起点位置
Prefix String 对 object 的 key 进行筛选,匹配指定前缀(prefix)的 objects
MaxKeys Int 最多返回的 objects 数量,默认为最大的1000
IsTruncated Int 表示返回的 objects 否被截断
Contents Array 返回的对象列表
Content Array 返回的对象属性,包含所有 objects 元信息的 list,包括 'ETag','StorageClass','Key','Owner','LastModified','Size' 等信息 Contents

简单上传对象

功能说明

上传对象到指定的存储桶中(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); 
}

参数说明

参数名称 类型 描述 父节点
Bucket String 存储桶名称,格式:BucketName-APPID
Key String 对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中,对象键为 doc/pic.jpg
ACL String 设置对象的 ACL,如 private、public-read
Body File/String 上传的内容
CacheControl String 缓存策略,设置 Cache-Control
ContentDisposition String 文件名称,设置 Content-Disposition
ContentEncoding String 编码格式,设置 Content-Encoding
ContentLanguage String 语言类型,设置 Content-Language
ContentLength Int 设置传输长度
ContentType String 内容类型,设置 Content-Type
Expires String 设置 Content-Expires
Metadata Array 用户自定义的文件元信息
StorageClass String 文件的存储类型,STANDARD 、 STANDARD_IA 、 ARCHIVE,默认值:STANDARD
ContentMD5 String 设置上传文件的 MD5 值用于校验
ServerSideEncryption String 服务端加密方法

查询对象元数据

功能说明

查询 Object 的 Meta 信息(HEAD Object)。

方法原型

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

请求示例

$cosClient = new Qcloud\Cos\Client(
    array(
        'region' => $region,
        'schema' => 'https', //协议头部,默认为 http
        '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);
}

参数说明

参数名称 类型 描述 父节点
Bucket String 存储桶名称,格式:BucketName-APPID
Key String 对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名
examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中,对象键为 doc/pic.jpg

返回结果示例

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] => 
            [WebsiteRedirectLocation] => 
            [ServerSideEncryption] => 
            [Metadata] => Array
                (
                    [md5] => af9f3b8eaf64473278909183abba1e31
                )
            [SSECustomerAlgorithm] => 
            [SSECustomerKeyMD5] => 
            [SSEKMSKeyId] => 
            [StorageClass] => 
            [RequestCharged] => 
            [ReplicationStatus] => 
            [RequestId] => NWNhMzU3Y2ZfMzFhYzM1MGFfODdhMF8xOTExM2U=
        )

)

返回结果说明

参数名称 类型 描述 父节点
CacheControl String 缓存策略,设置 Cache-Control
ContentDisposition String 文件名称,设置 Content-Disposition
ContentEncoding String 编码格式,设置 Content-Encoding
ContentLanguage String 语言类型,设置 Content-Language
ContentLength Int 设置传输长度
ContentType String 内容类型,设置 Content-Type
Metadata Array 用户自定义的文件元信息
StorageClass String 文件的存储类型,STANDARD 、 STANDARD_IA 、 ARCHIVE
ServerSideEncryption String 服务端加密方法
ETag String 文件的MD5值
Restore String 归档文件的回热信息

下载对象

功能说明

下载对象到本地(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',
        'ResponseCacheControl' => 'string',
        'ResponseContentDisposition' => 'string',
        'ResponseContentEncoding' => 'string',
        'ResponseContentLanguage' => 'string',
        'ResponseContentType' => 'string',
        'ResponseExpires' => 'string',
        */
    )); 
    // 请求成功
    print_r($result);
} catch (\Exception $e) {
    // 请求失败
    echo($e);
}

参数说明

参数名称 类型 描述 父节点
Bucket String 存储桶名称,格式:BucketName-APPID
Key String 对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名
examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中,对象键为 doc/pic.jpg
SaveAs String 保存到本地的本地文件路径
Range String 设置下载文件的范围,格式为 bytes=first-last
ResponseCacheControl String 设置响应头部 Cache-Control
ResponseContentDisposition String 设置响应头部 Content-Disposition
ResponseContentEncoding String 设置响应头部 Content-Encoding
ResponseContentLanguage String 设置响应头部 Content-Language
ResponseContentType String 设置响应头部 Content-Type
ResponseExpires String 设置响应头部 Content-Expires

返回结果示例

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
        )

)

返回结果说明

参数名称 类型 描述 父节点
Body File/String 下载内容
ETag String 文件的 MD5 值
Expires String Content-Expires
Metadata Array 用户自定义的文件元信息
StorageClass String 文件的存储类型,STANDARD 、 STANDARD_IA 、 ARCHIVE,默认值:STANDARD
ContentMD5 String 设置上传文件的 MD5 值用于校验
ServerSideEncryption String 服务端加密方法
CacheControl String 缓存策略,设置 Cache-Control
ContentDisposition String 文件名称,设置 Content-Disposition
ContentEncoding String 编码格式,设置 Content-Encoding
ContentLanguage String 语言类型,设置 Content-Language
ContentLength Int 设置传输长度
ContentType String 内容类型,设置 Content-Type
Metadata Array 用户自定义的文件元信息
Restore String 归档文件的回热信息

设置对象复制

将一个对象复制到目标路径(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);
}

参数说明

参数名称 类型 描述 父节点
Bucket String 存储桶名称,格式:BucketName-APPID
Key String 对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名
examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中,对象键为 doc/pic.jpg
CopySource String 描述拷贝源文件的路径,包含 Appid、Bucket、Key、Region,
例如 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg
MetadataDirective String 可选值为 Copy、Replaced。设置为 Copy 时,忽略设置的用户元数据信息直接复制,设置为 Replaced 时,按设置的元信息修改元数据,当目标路径和源路径一样时,必须设置为 Replaced

删除单个对象

功能说明

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

方法原型

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

请求示例

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

参数说明

参数名称 类型 描述 父节点
Bucket String 存储桶名称,格式:BucketName-APPID
Key String 对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名
examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中,对象键为 doc/pic.jpg

删除多个对象

功能说明

在存储桶中批量删除 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',
            ),  
            // ... repeated
        ),  
    )); 
    // 请求成功
    print_r($result);
} catch (\Exception $e) {
    // 请求失败
    echo($e);
}

参数说明

参数名称 类型 描述 父节点
Bucket String 存储桶名称,格式:BucketName-APPID
Objects Array 删除对象列表
Object Array 删除的对象 Objects
Key String 对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名
examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中,对象键为 doc/pic.jpg
Object

返回结果示例

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

返回结果说明

参数名称 类型 描述 父节点
Deleted Array 成功删除的对象的列表
Errors Array 失败删除的对象的列表
Key String 对象键 Deleted/Errors
Code String 失败错误码 Errors
Message String 失败错误信息 Errors

分块操作

查询分片上传

功能说明

查询指定存储桶中正在进行的分片上传(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);
}

参数说明

参数名称 类型 描述 父节点
Bucket String 存储桶名称,格式:BucketName-APPID
Delimiter String 默认为空,设置分隔符,比如设置/来模拟文件夹
EncodingType String 默认不编码,规定返回值的编码方式,可选值:url
KeyMarker String 标记返回 parts 的 list 的起点位置
UploadIdMarker String 标记返回 parts 的 list 的起点位置
Prefix String 默认为空,对 parts 的 key 进行筛选,匹配指定前缀(prefix)的 objects
MaxUploads Int 最多返回的 parts 数量,默认为最大的1000

返回结果示例

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
        )

)

返回结果说明

参数名称 类型 描述 父节点
Bucket String 存储桶名称,格式:BucketName-APPID
IsTruncated Int 表示返回的 objects 否被截断
Uploads Array 返回的分块列表
Upload Array 返回的分块属性 Uploads
Key String 对象健名 Upload
UploadId String 对象的分块上传 ID Upload
Initiator String 初始化该分片的操作者 Upload
Owner String 分块拥有者 Upload
StorageClass String 分块存储类型 Upload
Initiated String 分块初始化时间 Upload

分片上传对象

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

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

初始化分片上传

功能说明

初始化 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);
}

参数说明

参数名称 类型 描述 父节点
Bucket String 存储桶名称,格式:BucketName-APPID
Key String 对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名
examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中,对象键为 doc/pic.jpg
CacheControl String 缓存策略,设置 Cache-Control
ContentDisposition String 文件名称,设置 Content-Disposition
ContentEncoding String 编码格式,设置 Content-Encoding
ContentLanguage String 语言类型,设置 Content-Language
ContentLength Int 设置传输长度
ContentType String 内容类型,设置 Content-Type
Expires String 设置 Content-Expires
Metadata Array 用户自定义的文件元信息
StorageClass String 文件的存储类型,STANDARD 、 STANDARD_IA 、 ARCHIVE,默认值:STANDARD
ContentMD5 String 设置上传文件的 MD5 值用于校验
ServerSideEncryption String 服务端加密方法

返回结果示例

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

)

返回结果说明

参数名称 类型 描述 父节点
Bucket String 存储桶名称,格式:BucketName-APPID
Key String 对象键
UploadId String 对象分块上传的ID

查询已上传块

功能说明

查询特定分块上传操作中的已上传的块(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);
}

参数说明

参数名称 类型 描述 父节点
Bucket String 存储桶名称,格式:BucketName-APPID
Key String 对象键
UploadId String 对象分块上传的 ID
PartNumberMarker Int 标记返回 parts 的 list 的起点位置
MaxParts Int 最多返回的 parts 数量,默认最大值为1000

返回结果示例

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

)

返回结果说明

参数名称 类型 描述 父节点
Bucket String 存储桶名称,格式:BucketName-APPID
Key String 对象键
UploadId String 对象分块上传的 ID
IsTruncated Int 表示返回的 objects 否被截断
PartNumberMarker Int 标记返回 parts 的 list 的起点位置
MaxParts Int 最多返回的 parts 数量,默认最大值为1000
Initiator String 初始化该分片的操作者
Parts Array 返回的分块列表
Part Array 返回的分块属性 Parts
PartNumber Int 分块标号 Part
LastModified String 分块的最后上传时间 Part
ETag String 分块的 MD5 值 Part
Size String 分块的大小 Part

上传分块

分块上传文件(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);
}

参数说明

参数名称 类型 描述 父节点
Bucket String 存储桶名称,格式:BucketName-APPID
Key String 对象键
UploadId String 对象分块上传的 ID
Body File/String 上传的内容
PartNumber Int 上传分块的编号
ContentLength Int 设置传输长度
ContentMD5 String 设置上传文件的 MD5 值用于校验

返回结果示例

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

)

返回结果说明

参数名称 类型 描述 父节点
ETag String 分块的 MD5 值

完成分块上传

功能说明

完成整个文件的分块上传(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);
}

参数说明

参数名称 类型 描述 父节点
Bucket String 存储桶名称,格式:BucketName-APPID
Key String 对象键
UploadId String 对象分块上传的 ID
Parts Array 分块信息列表
Part Array 上传分块的内容信息 Parts
ETag String 分块内容的 MD5 Part
PartNumber Int 分块编号 Part

终止分块上传

功能说明

终止一个分块上传操作并删除已上传的块(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);
}

参数说明

参数名称 类型 描述 父节点
Bucket String 存储桶名称,格式:BucketName-APPID
Key String 对象键
UploadId String 对象分块上传的 ID

其他操作

恢复归档对象

功能说明

将归档类型的对象取回访问(POST Object restore)。

方法原型

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

请求示例

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

参数说明

参数名称 类型 描述 父节点
Bucket String 存储桶名称,格式:BucketName-APPID
Key String 对象键
Days String 设置临时副本的过期时间,单位(天)
CASJobParameters Array 恢复信息
Tier String 恢复数据时,Tier 可以指定为 CAS 支持的三种恢复类型,分别为 Expedited、Standard、Bulk CASJobParameters

设置对象 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";
}

参数说明

参数名称 类型 描述 父节点
Bucket String 存储桶名称,格式:BucketName-APPID
Key String 对象键
Grants Array ACL权限列表
Grant Array ACL权限信息 Grants
Grantee Array ACL权限信息 Grant
Type String 所有者权限类型 Grantee
Permission String 权限类型,可选值: FULL_CONTROL 、WRITE 、READ Grant
ACL String 整体权限类型,可选值: private 、 public-read
Owner String 存储桶所有者信息
DisplayName String 权限所有者的名字信息 Grantee / Owner
ID String 权限所有者 ID Grantee / Owner

获取对象 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=
        )
)

返回结果说明

参数名称 类型 描述 父节点
Grants Array ACL权限列表
Grant Array ACL权限信息 Grants
Grantee Array ACL权限信息 Grant
Permission String 权限类型,可选值: FULL_CONTROL 、WRITE 、 READ Grant
Owner String 存储桶所有者信息
DisplayName String 权限所有者的名字信息 Grantee / Owner
ID String 权限所有者 ID Grantee / Owner

高级接口(推荐)

该小节主要讲述由 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);
}