接口描述
- 接口名称: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 | 加密类型: |
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"
}
}]
}