获取文件列表

最近更新时间：2023-02-03 11:05:44

前往 GitHub 编辑 我的收藏

本页目录：

接口描述

接口名称：GetCoffer
接口功能：该请求接口可以列出数据保险箱内的部分或者全部对象。该接口的请求者需要对数据保险箱有读取权限。

说明：

如果您在保险箱中上传了一个对象，并立即调用 GetCoffer 接口，由于此接口的最终一致性特性，返回的结果中可能不会包含您刚上传的对象。

请求

请求示例

GET /<CofferName-APPID> HTTP/1.1
Host: service.cdcs.myqcloud.com
Date: GMT Date
Authorization: Auth String

说明：

Authorization: Auth String 的详情，请参见请求签名文档。

请求参数

名称	是否必选	类型	描述
prefix	否	string	对象键匹配前缀，限定响应中只包含指定前缀的对象键。
encoding-type	否	string	规定返回值的编码方式，可选值：url，代表返回的对象键为 URL 编码（百分号编码）后的值，例如“腾讯云”将被编码为`%E8%85%BE%E8%AE%AF%E4%BA%91`。
marker	否	string	起始对象键标记，从该标记之后（不含）按照 UTF-8 字典序返回对象键条目。
max-keys	否	integer	单次返回最大的条目数量，默认值为1000，最大为1000。注意：该参数会限制每一次 List 操作返回的最大条目数，数据保险箱在每次 List 操作中将返回不超过 max-keys 所设定数值的条目。

请求头

此接口仅使用公共请求头部，详情请参见公共请求头部文档。

请求体

此接口无请求体。

响应

响应头

此接口返回公共响应头部

响应体

查询成功，返回application/json数据，包含保险箱中的对象信息。不同场景下的响应体请参见下方的实际案例。

{
    "Name": "string",
    "EncodingType": "string",
    "Prefix": "string",
    "Marker": "string",
    "MaxKeys":integer,
    "IsTruncated": "boolean",
    "NextMarker": "string",
    "EncryptType": interger,
    "KeyId": "string",
    "KeyRegion": "string",
    "Locations": {
        "Location": ["Enum"]
    },
    "Contents": [{
        "Key": "string",
        "LastModified": "date",
        "ETag": "string",
        "Size": integer,
        "Owner": {
            "ID": "string",
            "DisplayName": "string"
        }
    }]
}

响应参数描述如下：

节点名称（关键字）	类型	描述
Name	string	保险箱的名称，格式为`<CofferName-APPID>`，例如`examplecoffer-1250000000`。
EncryptType	int	加密类型: 0 = 不加密 1 = 使用公共主密钥 2 = 使用 KMS 主密钥
KeyId	string	主密钥的 ID，仅当 EncryptType = 2时，返回该参数。
KeyRegion	string	主密钥的地域，仅当 EncryptType = 2时，返回该参数。
Locations	Object	保险箱所在地域列表。
Location	Enum	保险箱所在地域，枚举值请参见地域和访问域名文档。例如`ap-beijing，ap-hongkong，eu-frankfurt`等
EncodingType	string	编码格式，对应请求中的 encoding-type 参数，且仅当请求中指定了 encoding-type 参数才会返回该节点。
Prefix	string	对象键匹配前缀，对应请求中的 prefix 参数。
Marker	string	起始对象键标记，从该标记之后（不含）按照 UTF-8 字典序返回对象键条目，对应请求中的 marker 参数。
MaxKeys	integer	单次响应返回结果的最大条目数量，对应请求中的 max-keys 参数。注意：该参数会限制每一次 List 操作返回的最大条目数，CDCS 在每次 List 操作中将返回不超过 max-keys 所设定数值的条目。如果由于您设置了 max-keys 参数，导致单次响应中未列出所有对象，CDCS 会返回一项 nextmarker 参数作为您下次 List 请求的入参，以便您后续进行列出对象。
IsTruncated	boolean	响应条目是否被截断，布尔值，例如 true 或 false。
NextMarker	string	仅当响应条目有截断（IsTruncated 为 true）才会返回该节点，该节点的值为当前响应条目中的最后一个对象键，当需要继续请求后续条目时，将该节点的值作为下一次请求的 marker 参数传入。
Contents	Object	对象条目。

Contents 对象的描述：

节点名称（关键字）	类型	描述
Key	string	对象键。
LastModified	date	对象创建时间，为 ISO8601 格式，如 2019-05-24T10:56:40Z。
ETag	string	对象的实体标签（Entity Tag），是对象被创建时标识对象内容的信息标签，可用于检查对象的内容是否发生变化，例如“8e0b617ca298a564c3331da28dcb50df”，此头部并不一定返回对象的 MD5 值，而是根据对象上传和加密方式而有所不同。
Size	integer	对象大小，单位为 Byte。
Owner	Container	对象持有者信息。

Owner 对象的描述：

节点名称（关键字）	类型	描述
ID	string	对象持有者的 AppID。
DisplayName	string	对象持有者的名称。

错误码

此接口无特殊错误信息，全部错误信息请参见错误码文档。

示例

示例1：简单案例

请求

GET /examplecoffer-1250000000 HTTP/1.1
Host: service.cdcs.myqcloud.com
Date: Mon, 27 May 2019 11:26:14 GMT
Authorization: [Auth String]
Connection: close

响应

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 1517
Connection: close
Date: Mon, 27 May 2019 11:26:15 GMT
Server: tencent-cdcs
x-cdcs-coffer-region: ap-beijing
x-cdcs-request-id: NWNlYmM5NTdfZjI4NWQ2NF81ZmMwX2Q5N2E1****

{
    "Name": "examplecoffer-1250000000",
    "EncodingType": "",
    "Prefix": "",
    "Marker": "",
    "MaxKeys": 1000,
    "IsTruncated": "false",
    "NextMarker": "",
    "EncryptType": 0,
    "KeyId": "",
    "KeyRegion": "",
    "Locations": {
        "Location": ["ap-tianjin"]
    },
    "Contents": [{
        "Key": "test1.html",
        "LastModified": "2020-06-13T15:40:15+08:00",
        "ETag": "\"f797031f3210ce6494466d619610926c\"",
        "Size": 20,
        "Owner": {
            "ID": "1250000000",
            "DisplayName": "1250000000"
        }
    }, {
        "Key": "test2.html",
        "LastModified": "2020-06-13T15:40:15+08:00",
        "ETag": "\"f797031f3210ce6494466d619610926c\"",
        "Size": 20,
        "Owner": {
            "ID": "1250000000",
            "DisplayName": "1250000000"
        }
    }, {
        "Key": "test3.html",
        "LastModified": "2020-06-13T15:40:15+08:00",
        "ETag": "\"f797031f3210ce6494466d619610926c\"",
        "Size": 90,
        "Owner": {
            "ID": "1250000000",
            "DisplayName": "1250000000"
        }
    }]
}

示例2：需分页时获取第一页

请求

GET /examplecoffer-1250000000 HTTP/1.1
Host: service.cdcs.myqcloud.com
Date: Mon, 27 May 2019 11:07:30 GMT
Authorization: [Auth String]
Connection: close

响应

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 321247
Connection: close
Date: Mon, 27 May 2019 11:07:30 GMT
Server: tencent-cdcs
x-cdcs-coffer-region: ap-beijing
x-cdcs-request-id: NWNlYmM0ZjJfZDcyNzVkNjRfNjQ5OV9lNzdk****

{
    "Name": " examplecoffer -1250000000",
    "EncodingType": "",
    "Prefix": "",
    "Marker": "",
    "MaxKeys": 1000,
    "IsTruncated": "true",
    "NextMarker": "",
    "EncryptType": 0,
    "KeyId": "",
    "KeyRegion": "",
    "Locations": {
        "Location": ["ap-tianjin"]
    },
    "Contents": [{
        "Key": "test1.html",
        "LastModified": "2020-06-13T15:40:15+08:00",
        "ETag": "\"f797031f3210ce6494466d619610926c\"",
        "Size": 20,
        "Owner": {
            "ID": "1250000000",
            "DisplayName": "1250000000"
        }
    }, {
        "Key": "test2.html",
        "LastModified": "2020-06-13T15:40:15+08:00",
        "ETag": "\"f797031f3210ce6494466d619610926c\"",
        "Size": 20,
        "Owner": {
            "ID": "1250000000",
            "DisplayName": "1250000000"
        }
    }

    ...

    , {
        "Key": "test3.html",
        "LastModified": "2020-06-13T15:40:15+08:00",
        "ETag": "\"f797031f3210ce6494466d619610926c\"",
        "Size": 20,
        "Owner": {
            "ID": "1250000000",
            "DisplayName": "1250000000"
        }
    }]
}

示例3：需分页时获取后续页

请求

GET /examplecoffer-1250000000?marker=example-object-1000.jpg HTTP/1.1
Host: service.cdcs.myqcloud.com
Date: Mon, 27 May 2019 11:08:36 GMT
Authorization: [Auth String]
Connection: close

响应

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 1834
Connection: close
Date: Mon, 27 May 2019 11:08:36 GMT
Server: tencent-cdcs
x-cdcs-coffer-region: ap-beijing
x-cdcs-request-id: NWNlYmM1MzRfZmVhODBiMDlfMmViNjRfZDQw****

{
    "Name": " examplecoffer -1250000000",
    "EncodingType": "2",
    "Prefix": "",
    "Marker": " test1.html ",
    "MaxKeys": 1000,
    "IsTruncated": "true",
    "NextMarker": " test7.html ",
    "EncryptType": 0,
    "KeyId": "aaaa-bbbb-cccc",
    "KeyRegion": "ap- tianjin ",
    "Locations": {
        "Location": ["ap-tianjin"]
    },
    "Contents": [{
        "Key": "test1.html",
        "LastModified": "2020-06-13T15:40:15+08:00",
        "ETag": "\"f797031f3210ce6494466d619610926c\"",
        "Size": 20,
        "Owner": {
            "ID": "1250000000",
            "DisplayName": "1250000000"
        }
    }, {
        "Key": "test2.html",
        "LastModified": "2020-06-13T15:40:15+08:00",
        "ETag": "\"f797031f3210ce6494466d619610926c\"",
        "Size": 20,
        "Owner": {
            "ID": "1250000000",
            "DisplayName": "1250000000"
        }
    }

    ...

    , {
        "Key": "test3.html",
        "LastModified": "2020-06-13T15:40:15+08:00",
        "ETag": "\"f797031f3210ce6494466d619610926c\"",
        "Size": 20,
        "Owner": {
            "ID": "1250000000",
            "DisplayName": "1250000000"
        }
    }]
}

上一篇: 查询保险箱列表下一篇: 下载文件