列出目录

最近更新时间:2017-09-14 16:30:56

功能描述

使用该 API 列出指定目录下的所有文件目录,可带前缀查询,仅支持向后翻页。成功列出目录的前提条件是 Bucket 中已存在目录。如果该 Bucket 中没有文件目录则请求不成功。

注意:
在返回内容中不包含 biz_attr 字段,如需查询,请调用查询目录属性接口。

请求

语法示例:

GET /files/v2/<APPID>/<BucketName>/<DirName>/?op=list&num=20 HTTP/1.1
Host: <Region>.file.myqcloud.com
Authorization: <MultiEffectSignature>

Authorization: 多次有效签名(详细参见 签名算法 章节)

语法说明:
请求方法中发送不同的请求地址,可以获取不同的响应结果。

  • 直接查询 bucket 目录下所有文件和目录,请求路径为:
    /files/v2/<APPID>/<BucketName>/
    
  • 查询指定 bucket 中文件夹 DirName 下的文件和目录,请求路径为:
    /files/v2/<APPID>/<BucketName>/<DirName>/
    
  • 带前缀的查询,请求路径为:
    /files/v2/<APPID>/<BucketName>/<DirName>/[prefix]
    

请求参数

该请求的请求参数和描述如下:

参数名称 描述 类型 必选
op 操作类型,填 “list” String
num 本次查询所要列出的目录总数,最大支持 199 Number
context 用于翻页的透传字段,从响应的返回内容中得到。
若查看第一页,则将空字符串作为 context 传入。若需要翻页,需要将前一页返回内容中的 context 透传到参数中
String

响应

响应体

该响应体返回为 application/json 数据,包含完整节点数据的内容展示如下:

{
    "code":0,
    "message":"SUCCESS",
    "request_id":"NTk5YWM5ZjdfY2JhMzNiMGFfMTUwNV8xZDdjYTI=",
    "data":{
    "context":"",
    "infos":[],
    "listover":true
    }
}

具体的参数描述如下:

参数名称 描述 类型
code 服务端返回码,如果没有发生任何错误取值为0;如果发生错误该参数指称具体的错误码。COS 服务相关的错误码可以查看 COS 错误码汇总 Number
request_id 该请求的唯一标识 id String
message 服务端提示内容,如果发生错误该字段将详细描述发生错误的情况。 String
data 服务端返回的应答数据,该内容代表了接口返回的具体的业务数据。 Object

data 数据集参数描述:

参数名称 描述 类型
context 创建时间,10 位 Unix 时间戳( UNIX 时间是从协调世界时1970年1月1日0时0分0秒起的总秒数) String
listover 是否有内容可以继续往后翻页 Boolean
infos 文件和文件夹列表,若当前目录下不存在文件或文件夹,则该返回值可能为空 Array

infos 数据集参数描述:

参数名称 描述 类型
name 文件名 String
filesize 文件大小,当类型为文件时返回 Number
filelen 文件已传输大小,当类型为文件时返回 Number
sha 文件 sha,当类型为文件时返回 String
ctime 创建时间,10 位 Unix 时间戳(UNIX 时间是从协调世界时 1970 年 1 月 1 日 0 时 0 分 0 秒起的总秒数) Number
mtime 修改时间,10 位 Unix 时间戳(UNIX 时间是从协调世界时 1970 年 1 月 1 日 0 时 0 分 0 秒起的总秒数) Number
access_url 生成的资源可访问的 cdn url,当类型为文件时返回 String
authority 如果没有对文件单独设置该属性,则可能不会返回该字段。枚举值:
eInvalid(表示继承 bucket 的读写权限);
eWRPrivate(私有读写);
eWPrivateRPublic(公有读私有写)。
说明:文件可以和 bucket 拥有不同的权限类型,已经设置过权限的文件如果想要撤销,将会直接被赋值为 eInvalid,即继承 bucket 的权限
String
source_url 生成的资源可访问的源站 url,当类型为文件时返回 String

实际案例

请求

GET /files/v2/1252448703/lewzylu02/testfolder/?op=list&num=20 HTTP/1.1
Host: gz.file.myqcloud.com
Authorization: DUbxmGI7DuyqWQxB+LaUYDII+WdhPTEyNTI0NDg3MDMmaz1BS0lEMTVJc3NraUJRS1RaYkFvNldoZ2NCcVZsczlTbXVHMDAmZT0xNTAzMzE2NjA1JnQ9MTUwMzMxNjQyNSZyPTExMjMwJmY9JmI9bGV3enlsdTAy

响应

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 135
Connection: keep-alive
Date: Mon, 21 Aug 2017 11:54:31 GMT
Server: tencent-cos
x-cos-request-id: NTk5YWM5ZjdfY2JhMzNiMGFfMTUwNV8xZDdjYTI=

{
    "code": 0, 
    "message": "SUCCESS", 
    "data": {
        "context": "/accesslog/aaa/bbb/14709104920.89088300.txt", 
        "infos": [
            {
                "access_url": "http://accesslog-10055004.file.myqcloud.com/aaa/bbb/14709104920.63503400.txt", 
                "authority": "eInvalid", 
                "ctime": 1470910492, 
                "filelen": 10264, 
                "filesize": 10264, 
                "mtime": 1470910492, 
                "name": "14709104920.63503400.txt", 
                "preview_url": "http://accesslog-10055004.preview.myqcloud.com/aaa/bbb/14709104920.63503400.txt?cmd=txt_preview", 
                "sha": "cad7d66231fa548b2e5b5f431fcf8f1bf028d0b0", 
                "source_url": "http://accesslog-10055004.cossh.myqcloud.com/aaa/bbb/14709104920.63503400.txt"
            }, 
            {
                "access_url": "http://accesslog-10055004.file.myqcloud.com/aaa/bbb/14709104920.71280700.txt", 
                "authority": "eInvalid", 
                "ctime": 1470910492, 
                "filelen": 10264, 
                "filesize": 10264, 
                "mtime": 1470910492, 
                "name": "14709104920.71280700.txt", 
                "preview_url": "http://accesslog-10055004.preview.myqcloud.com/aaa/bbb/14709104920.71280700.txt?cmd=txt_preview", 
                "sha": "4ba80f5c809954e93b97de3a3bb0950f6374bdf7", 
                "source_url": "http://accesslog-10055004.cossh.myqcloud.com/aaa/bbb/14709104920.71280700.txt"
            }, 
            {
                "access_url": "http://accesslog-10055004.file.myqcloud.com/aaa/bbb/14709104920.77835100.txt", 
                "authority": "eInvalid", 
                "ctime": 1470910492, 
                "filelen": 10264, 
                "filesize": 10264, 
                "mtime": 1470910492, 
                "name": "14709104920.77835100.txt", 
                "preview_url": "http://accesslog-10055004.preview.myqcloud.com/aaa/bbb/14709104920.77835100.txt?cmd=txt_preview", 
                "sha": "2130bd5f70e0da1a50e9ad70907f5d694ad88bb4", 
                "source_url": "http://accesslog-10055004.cossh.myqcloud.com/aaa/bbb/14709104920.77835100.txt"
            }, 
            {
                "access_url": "http://accesslog-10055004.file.myqcloud.com/aaa/bbb/14709104920.83866400.txt", 
                "authority": "eInvalid", 
                "ctime": 1470910492, 
                "filelen": 10264, 
                "filesize": 10264, 
                "mtime": 1470910492, 
                "name": "14709104920.83866400.txt", 
                "preview_url": "http://accesslog-10055004.preview.myqcloud.com/aaa/bbb/14709104920.83866400.txt?cmd=txt_preview", 
                "sha": "1f47ec790b23c950869449309797737e39f1cb92", 
                "source_url": "http://accesslog-10055004.cossh.myqcloud.com/aaa/bbb/14709104920.83866400.txt"
            }, 
            {
                "access_url": "http://accesslog-10055004.file.myqcloud.com/aaa/bbb/14709104920.89088300.txt", 
                "authority": "eInvalid", 
                "ctime": 1470910492, 
                "filelen": 10264, 
                "filesize": 10264, 
                "mtime": 1470910493, 
                "name": "14709104920.89088300.txt", 
                "preview_url": "http://accesslog-10055004.preview.myqcloud.com/aaa/bbb/14709104920.89088300.txt?cmd=txt_preview", 
                "sha": "afe17bb32c0835e8b9ce69450f95e3e6f2af4606", 
                "source_url": "http://accesslog-10055004.cossh.myqcloud.com/aaa/bbb/14709104920.89088300.txt"
            }
        ], 
        "listover": false
    }
}