控制台指南

最佳实践

开发者指南

API 文档

SDK 文档

诚邀爱技术、爱分享的你,成为文档内容共建者> HOT

简介

本文档提供关于列出对象操作相关的 API 概览以及 SDK 示例代码。

API 操作名 操作描述
GET Bucket(List Objects) 查询对象列表 查询存储桶下的部分或者全部对象
GET Bucket Object Versions 查询对象及其历史版本列表 查询存储桶下的部分或者全部对象及其历史版本信息

查询对象列表

功能说明

查询指定存储桶中所有的对象(List Objects)。

方法原型

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

请求示例

示例一:查询指定前缀、指定开始对象的对象列表

<?php

require dirname(__FILE__) . '/../vendor/autoload.php';

$secretId = "SECRETID"; //替换为用户的 secretId,请登录访问管理控制台进行查看和管理,https://console.cloud.tencent.com/cam/capi
$secretKey = "SECRETKEY"; //替换为用户的 secretKey,请登录访问管理控制台进行查看和管理,https://console.cloud.tencent.com/cam/capi
$region = "ap-beijing"; //替换为用户的 region,已创建桶归属的region可以在控制台查看,https://console.cloud.tencent.com/cos5/bucket
$cosClient = new Qcloud\Cos\Client(
    array(
        'region' => $region,
        'schema' => 'https', //协议头部,默认为http
        'credentials'=> array(
            'secretId'  => $secretId ,
            'secretKey' => $secretKey)));

try {
    $result = $cosClient->listObjects(array(
        'Bucket' => 'examplebucket-125000000', //存储桶名称,由BucketName-Appid 组成,可以在COS控制台查看 https://console.cloud.tencent.com/cos5/bucket
        'Delimiter' => '/', //Delimiter表示分隔符, 设置为/表示列出当前目录下的object, 设置为空表示列出所有的object
        'EncodingType' => 'url',//编码格式,对应请求中的 encoding-type 参数
        'Marker' => 'prefix/picture.jpg',//起始对象键标记
        'Prefix' => 'prfix/', //Prefix表示列出的object的key以prefix开始
        'MaxKeys' => 1000, // 设置最大遍历出多少个对象, 一次listObjects最大支持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 的起点位置,通过返回的Key值设为Marker实现翻页
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

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

功能说明

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

方法原型

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

请求示例

示例一:查询历史对象列表

<?php

require dirname(__FILE__) . '/../vendor/autoload.php';

$secretId = "SECRETID"; //替换为用户的 secretId,请登录访问管理控制台进行查看和管理,https://console.cloud.tencent.com/cam/capi
$secretKey = "SECRETKEY"; //替换为用户的 secretKey,请登录访问管理控制台进行查看和管理,https://console.cloud.tencent.com/cam/capi
$region = "ap-beijing"; //替换为用户的 region,已创建桶归属的region可以在控制台查看,https://console.cloud.tencent.com/cos5/bucket
$cosClient = new Qcloud\Cos\Client(
    array(
        'region' => $region,
        'schema' => 'https', //协议头部,默认为http
        'credentials'=> array(
            'secretId'  => $secretId ,
            'secretKey' => $secretKey)));

try {
    $result = $cosClient->listObjectVersions(array(
        'Bucket' => 'examplebucket-1250000000', //存储桶名称,由BucketName-Appid 组成,可以在COS控制台查看 https://console.cloud.tencent.com/cos5/bucket
        'Delimiter' => '',
        'EncodingType' => 'url',
        'KeyMarker' => 'doc/picture.jpg',
        'VersionIdMarker' => 'MTg0NDUxODMyMTE2ODY0OTExOTk3W',
        'Prefix' => 'doc',
        'MaxKeys' => 1000,
    )); 
    print_r($result);
} catch (\Exception $e) {
    echo($e);
}

参数说明

参数名称 类型 描述 是否必填
Bucket String 存储桶名称,由 BucketName-APPID 构成
Prefix String 默认为空,对对象的对象键进行筛选,匹配 prefix 为前缀的对象
Delimiter String 默认为空,设置分隔符,例如设置/来模拟文件夹
KeyMarker String 默认以 UTF-8 二进制顺序列出条目,标记返回对象的 list 的 Key 的起点位置
VersionIdMarker String 默认以 UTF-8 二进制顺序列出条目,标记返回对象的 list 的 VersionId 的起点位置
MaxKeys Int 最多返回的对象数量,默认为最大的1000
EncodingType String 默认不编码,规定返回值的编码方式,可选值:url

返回结果示例

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

                    [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] => 1250000000
                                )
                        )
                    )
            [RequestId] => NWQwOGVkZGRfMjViMjU4NjRfODNjN18xMTE5YWI4
        )

)

返回结果说明

参数名称 类型 描述 父节点
Name String 存储桶名称,格式:BucketName-APPID
Delimiter String 设置分隔符,例如设置/来模拟文件夹
EncodingType String 规定返回值的编码方式
KeyMarker String 默认以 UTF-8 二进制顺序列出条目,标记返回对象的 list 的 Key 的起点位置
VersionIdMarker String 默认以 UTF-8 二进制顺序列出条目,标记返回对象的 list 的 VersionId 的起点位置
NextKeyMarker String 当 IsTruncated 为 true 时,标记下一次返回对象的 list 的 Key 的起点位置
NextVersionIdMarker String 当 IsTruncated 为 true 时,标记下一次返回对象的 list 的 VersionId 的起点位置
Prefix String 对 object 的 key 进行筛选,匹配指定前缀(prefix)的 objects
MaxKeys Int 最多返回的 objects 数量,默认为最大的1000
IsTruncated Int 表示返回的 objects 否被截断
Versions Array 包含所有多个版本对象元数据的 list
Version Array 包含所有多个版本对象元数据的 list,包括 'ETag','StorageClass','Key','VersionId','IsLatest','Owner','LastModified','Size' 等信息 Versions
CommonPrefixes Array 所有以 Prefix 开头,以 Delimiter 结尾的对象被归到同一类
目录