NAV Navbar
Logo
  • 接口认证
  • 接口调用限制
  • 接口列表
  • 异常处理
  • 接口认证

    OAuth2

    亿方云开放平台使用OAuth2作为接口的授权以及认证方式。亿方云开放平台提供了OAuth2的授权码模式以及密码模式,其中对外开放的只有授权码模式,若需要使用密码模式,请与客服联系。

    认证接口

    授权页

    URL

    https://oauth.fangcloud.com/oauth/authorize

    HTTP请求方式

    GET

    URL参数

    参数字段 字段类型 字段说明
    response_type string 必须为code
    client_id string 应用申请时提供的client_id
    redirect_uri string 回调地址,需要和应用申请时填写的回调地址相同
    state string state参数,由第三方传递,无特殊要求

    请求类似于:https://oauth.fangcloud.com/oauth/authorize?response_type=code&client_id=xxxxx&redirect_uri=http://xxx.xxx.xxx&state=xxx

    返回结果

    如果用户未登录,则会跳转到登录页,登录后如果未授权,则会302跳转到授权页,如果用户已经授权,则会302跳转到redirect_uri并且带上授权码和state,类似于http://xxx.xxx.xxx?code=xxx&state=xxx

    获得token

    URL

    https://oauth.fangcloud.com/oauth/token

    HTTP请求方式

    POST

    HTTP Header

    该接口使用Basic Auth的方式校验client的信息。具体做法是在header中添加类似于"Authorization: Basic xxxxxxxxx"。其中"xxxxxxxxx"是通过client_id和client_secret算出来的,具体算法为Base64Encode(client_id + ":" + client_secret)

    URL参数

    参数字段 字段类型 字段说明
    grant_type string 必须为authorization_code
    code string 授权码,即回调地址接收到的授权码,授权码的有效期为5分钟,用过一次,无论成功还是失败,授权码都会失效
    redirect_uri string 回调地址,需要和应用申请时填写的回调地址相同

    请求类似于:https://oauth.fangcloud.com/oauth/token?grant_type=authorization_code&code=xxx&redirect_uri=http://xxx.xxx.xxx

    返回示例

    {
        "access_token": "a2f97704-ab83-4719-aa4c-781be761906c",
        "token_type": "bearer",
        "refresh_token": "0d667a27-66b5-4a69-8872-2272b9f373ed",
        "expires_in": 21586,
        "scope": "all"
    }
    

    返回字段说明

    返回字段 字段类型 字段说明
    access_token string 接口访问标识
    token_type string 目前固定为bearer
    refresh_token string 用来刷新access_token,有效时间为30天
    expires_in int access_token的有效时间,单位为s
    scope string 目前固定为"all"

    刷新token

    URL

    https://oauth.fangcloud.com/oauth/token

    HTTP请求方式

    POST

    HTTP Header

    该接口使用Basic Auth的方式校验client的信息。具体做法是在header中添加类似于"Authorization: Basic xxxxxxxxx"。其中"xxxxxxxxx"是通过client_id和client_secret算出来的,具体算法为Base64Encode(client_id + ":" + client_secret)

    URL参数

    参数字段 字段类型 字段说明
    grant_type string 必须为refresh_token
    refresh_token string 即获取到的refresh_token

    请求类似于:https://oauth.fangcloud.com/oauth/token?grant_type=refresh_token&refresh_token=xxx

    返回示例

    {
        "access_token": "a2f97704-ab83-4719-aa4c-781be761906c",
        "token_type": "bearer",
        "refresh_token": "0d667a27-66b5-4a69-8872-2272b9f373ed",
        "expires_in": 21586,
        "scope": "all"
    }
    

    返回字段说明

    返回字段 字段类型 字段说明
    access_token string 新的接口访问标识
    token_type string 目前固定为bearer
    refresh_token string 用来刷新access_token,有效时间为30天
    expires_in int access_token的有效时间,单位为s
    scope string 目前固定为"all"

    接口调用限制

    目前对于开放平台的请求, 我们做了请求的频次限制, 在所有api请求的返回结果中会有三个header表示频次限制相关的信息

    返回header 字段类型 字段说明
    X-Rate-Limit-Limit int 当前接口请求次数的上限, 固定数值
    X-Rate-Limit-Remaining int 当前接口允许请求的剩余次数
    X-Rate-Limit-Reset int 当前接口允许请求的剩余次数恢复到上限所需要的时间(单位为秒)

    当请求超过了频次限制, 返回结果的HTTP Status Code为429, 返回body如下

    {
      "errors": [
        {
          "code": "rate_limit",
          "msg": "Rate limit exceeded!"
        }
      ],
      "request_id": "d3e1088f-28af-495d-b7ee-a9e58e989b76"
    }
    

    接口列表

    v1所有接口保持不变,不会新增接口,建议升级或直接使用v2版本

    通用参数

    所有的接口在访问时需要在HTTP header中带上access_token。对于含有请求参数的接口,通常是一些POST、PUT或者DELETE接口,还需要设置Content-Type来指定参数的格式。如果需要访问不同版本的API,就需要在请求路径上指定具体版本,如果需要返回不同格式的response body,那么还需要设置Accept。所有的参数都应该采用utf-8的编码:

    Headers:

    若接口访问成功,我们会返回json格式的response,并且HTTP的status code为200。所有请求成功的response的json都会带有"success: true"。response的header里的X-Fangcloud-Version表示此次请求访问的api的版本号。

    文件(FILE)操作

    获取文件信息

    URL

    https://open.fangcloud.com/api/file/{id}/info

    HTTP请求方式

    GET

    路径参数

    参数字段 字段类型 字段说明
    id long 文件id

    返回示例

    {
      "extension_category": "cad",
      "comments_count": 0,
      "type": "file",
      "id": 100000,
      "name": "aaa",
      "size": 3044,
      "created_at": 1417429563,
      "modified_at": 1463552148,
      "description": "ddd",
      "path": [
        {
          "type": "folder",
          "id": 0,
          "name": "全部文件"
        },
        {
          "type": "folder",
          "id": 59990,
          "name": "test"
        }
      ],
      "owned_by": {
        "id": 449,
        "name": "qyang1",
        "login": "qyang1@admin.com",
        "enterprise_id": 89
      },
      "shared": false,
      "parent": {
        "type": "folder",
        "id": 59990,
        "name": "test"
      },
      "sequence_id": 0,
      "success": true
    }
    

    返回字段说明

    返回字段 字段类型 字段说明
    comments_count int 评论数,目前都为0
    type string 固定为"file"
    id long 文件id
    name string 文件名称
    extension_category string 扩展名分类
    size long 文件大小
    created_at timestamp 文件创建时间
    modified_at timestamp 文件更新时间
    description string 文件描述
    path folder数组 所有的祖先文件夹
    owned_by user 所有者
    shared boolean 是否被分享,目前都为false
    parent folder 父文件夹
    in_trash boolean 是否在回收站中
    is_deleted boolean 是否已经被删除
    sequence_id long 目前没有用
    success boolean 请求是否成功

    错误码列表

    更新文件信息

    URL

    https://open.fangcloud.com/api/file/{id}/update

    HTTP请求方式

    PUT

    路径参数

    参数字段 字段类型 字段说明
    id int 文件id

    POST Body

    {
        "name": "new name",
        "description": "new description"
    }
    

    参数说明

    参数字段 字段类型 是否必须 字段说明
    name string 文件名,暂时不支持修改扩展名
    description string 文件描述

    name 和 description 至少需要传一个

    返回示例

    {
      "extension_category": "cad",
      "comments_count": 0,
      "type": "file",
      "id": 100000,
      "name": "new name",
      "size": 3044,
      "created_at": 1417429563,
      "modified_at": 1463552148,
      "description": "new description",
      "path": [
        {
          "type": "folder",
          "id": 0,
          "name": "全部文件"
        },
        {
          "type": "folder",
          "id": 59990,
          "name": "test"
        }
      ],
      "owned_by": {
        "id": 449,
        "name": "qyang1",
        "login": "qyang1@admin.com",
        "enterprise_id": 89
      },
      "shared": false,
      "parent": {
        "type": "folder",
        "id": 59990,
        "name": "test"
      },
      "sequence_id": 0,
      "success": true
    }
    

    返回字段说明

    返回字段 字段类型 字段说明
    extension_category string 扩展名分类
    comments_count int 评论数,目前都为0
    type string 固定为"file"
    id long 文件id
    name string 文件名称
    size long 文件大小
    created_at timestamp 文件创建时间
    modified_at timestamp 文件更新时间
    description string 文件描述
    path folder数组 所有的祖先文件夹
    owned_by user 所有者
    shared boolean 是否被分享,目前都为false
    parent folder 父文件夹
    sequence_id long 目前没有用
    in_trash boolean 是否在回收站中
    is_deleted boolean 是否已经被删除
    success boolean 请求是否成功

    错误码列表

    删除文件至回收站

    支持批量操作

    URL

    https://open.fangcloud.com/api/file/delete

    HTTP请求方式

    DELETE

    POST Body

    {
        "file_ids": [4063821, 85723]
    }
    

    参数说明

    参数字段 字段类型 是否必须 字段说明
    file_ids long数组 文件id

    返回示例

    {
      "success": true
    }
    

    返回字段说明

    错误码列表

    从回收站删除文件

    支持批量操作

    URL

    https://open.fangcloud.com/api/file/delete_from_trash

    HTTP请求方式

    DELETE

    POST Body

    仅删除某些文件:

    {
        "file_ids": [4063821, 85723]
    }
    

    清空回收站中的文件:

    {
        "clear_trash": true
    }
    

    参数说明

    仅删除某些文件:

    参数字段 字段类型 是否必须 字段说明
    file_ids long数组 文件id

    清空回收站中的文件:

    参数字段 字段类型 是否必须 字段说明
    clear_trash boolean 是否需要清空回收站中的文件,在此处场景肯定为true

    返回示例

    {
      "success": true
    }
    

    返回字段说明

    错误码列表

    从回收站恢复文件

    支持批量操作

    URL

    https://open.fangcloud.com/api/file/restore_from_trash

    HTTP请求方式

    POST

    POST Body

    仅恢复某些文件:

    {
        "file_ids": [4063821, 85723]
    }
    

    恢复回收站所有文件:

    {
        "restore_all": true
    }
    

    参数说明

    仅恢复某些文件:

    参数字段 字段类型 是否必须 字段说明
    file_ids long数组 文件id

    恢复回收站所有文件:

    参数字段 字段类型 是否必须 字段说明
    restore_all boolean 是否需要恢复回收站所有文件,在此处场景肯定为true

    返回示例

    {
      "success": true
    }
    

    返回字段说明

    错误码列表

    移动文件

    URL

    https://open.fangcloud.com/api/file/move

    HTTP请求方式

    POST

    POST Body

    {
        "file_ids": [1, 2, 3],
        "target_folder_id": 4
    }
    

    参数说明

    参数字段 字段类型 是否必须 字段说明
    file_ids long数组 被移动的文件id
    target_folder_id long 移动至的文件夹id

    返回示例

    {
      "success": true
    }
    

    返回字段说明

    错误码列表

    获取新文件上传地址

    URL

    https://open.fangcloud.com/api/file/upload

    HTTP请求方式

    POST

    POST Body

    {
        "parent_id": 1234,
        "name": "test.doc",
        "upload_type": "api"
    }
    

    参数说明

    参数字段 字段类型 是否必须 字段说明
    parent_id long 上传至的文件夹id
    name string 文件名称,文件名称必须是1到222个字符,并且不能含有/ ? : * \" > < \
    upload_type string 上传类型,目前固定为api

    返回示例

    {
      "presign_url": "https://upload.fangcloud.com/upload/9aeda9c9c9ee4edd9199e102989ec43c/76404f20763228f072dacd099ae1622beb05e666082b0f9c0df1ae1aaf3e1422",
      "success": true
    }
    

    返回字段说明

    返回字段 字段类型 字段说明
    presign_url string 上传链接,接下来往该链接上传即可上传文件,上传链接的有效时间为1个小时,且只能被使用一次

    错误码列表

    获取文件上传新版本地址

    URL

    https://open.fangcloud.com/api/file/{id}/new_version

    HTTP请求方式

    POST

    路径参数

    参数字段 字段类型 字段说明
    id long 文件id

    POST Body

    {
        "name": "test.doc",
        "upload_type": "api",
        "remark": "test"
    }
    

    参数说明

    参数字段 字段类型 是否必须 字段说明
    name string 新版本文件名称,文件名称必须是1到222个字符,并且不能含有\ / ? : * \" > < \
    upload_type string 上传类型,目前固定为api
    remark string 上传新版本的备注。

    返回示例

    {
      "presign_url": "https://upload.fangcloud.com/upload/9aeda9c9c9ee4edd9199e102989ec43c/76404f20763228f072dacd099ae1622beb05e666082b0f9c0df1ae1aaf3e1422",
      "success": true
    }
    

    返回字段说明

    返回字段 字段类型 字段说明
    presign_url url 上传链接,接下来往该链接上传即可上传文件,上传链接的有效时间为1个小时,且只能被使用一次

    错误码列表

    文件上传

    URL

    类似于https://upload.fangcloud.com/upload/xxxx/xxxxxx这样的链接

    上传方式

    拿到上传地址之后,建议通过multipart的方式进行上传

    返回示例

    {
      "new_file": {
        "extension": "",
        "created_at": 1466131038,
        "modified_at": 1466131038,
        "owned_by": {
          "id": 6072,
          "name": "测试账号",
          "login": "ceshi@admin.com",
          "enterprise_id": 700
        },
        "description": "",
        "remark": "",
        "id": 41000100000,
        "name": "aaa",
        "typed_id": "file_41000100000",
        "user_id": 6072,
        "size": 1366193,
        "parent_folder_id": 41000000007,
        "in_trash": false,
        "is_deleted": false
      },
      "success": true
    }
    

    获取文件的下载地址

    URL

    https://open.fangcloud.com/api/file/{id}/download

    HTTP请求方式

    GET

    路径参数

    参数字段 字段类型 字段说明
    id long 文件id

    返回示例

    {
      "download_urls": {
        "81503": "https://download.fangcloud.com/download/cd83d521b38b43bcace629a69f27422d/06b907d00e70d79ad114b7e2142126efa4d808d97e680bb6bbc4bb5924f6ee80/3-%E9%80%9A%E8%AE%AF%E5%BD%95+%284%29.xlsx"
      },
      "success": true
    }
    

    返回字段说明

    返回字段 字段类型 字段说明
    download_urls key为file_id, value为url组成的map 下载链接,访问该下载链接即可下载文件,下载链接的有效时间为1个小时,且只能被使用一次

    错误码列表

    预览文件

    分为发起预览请求和得到当前预览转换的进度,如果当前的进度为预览转换成功,则会得到预览文件的下载地址。

    我们可转换成的预览类型有:

    每种预览类型支持的文件格式如下:

    预览类型 支持的文件格式
    image_64 psd,png,jpg,jpeg,jpf,jp2,gif,tif,tiff,bmp,aix,ico,svg,ps,eps,ai
    image_128 psd,png,jpg,jpeg,jpf,jp2,gif,tif,tiff,bmp,aix,ico,svg,ps,eps,ai
    image_1024 doc,docx,odt,rtf,wps,yxls,xls,xlsx,ods,csv,et,ppt,pptx,odp,dps,markdown,md,mdown,html,xhtml,htm,tsv,as,as3,asm,bat,c,cc,cmake,cpp,cs,csh,css,cxx,diff,erb,groovy,h,haml,hh,java,js,less,m,make,ml,mm,php,pl,plist,properties,py,rb,sass,scala,scm,script,sh,sml,sql,txt,vi,vim,xml,xsd,xsl,xslt,yaml,pdf,psd,png,jpg,jpeg,jpf,jp2,gif,tif,tiff,bmp,aix,ico,svg,ps,eps,ai,dwg,dxf
    image_2048 psd,png,jpg,jpeg,jpf,jp2,gif,tif,tiff,bmp,aix,ico,svg,ps,eps,ai,dwg,dxf
    pdf doc,docx,odt,rtf,wps,yxls,xls,xlsx,ods,csv,et,ppt,pptx,odp,dps,markdown,md,mdown,html,xhtml,htm,tsv,as,as3,asm,bat,c,cc,cmake,cpp,cs,csh,css,cxx,diff,erb,groovy,h,haml,hh,java,js,less,m,make,ml,mm,php,pl,plist,properties,py,rb,sass,scala,scm,script,sh,sml,sql,txt,vi,vim,xml,xsd,xsl,xslt,yaml,pdf,dwg,dxf

    URL

    https://open.fangcloud.com/api/file/{id}/preview

    HTTP请求方式

    POST

    路径参数

    参数字段 字段类型 字段说明
    id long 文件id

    POST Body

    {
        "force_regenerate": false,
        "kind": "image_64"
    }
    

    参数说明

    参数字段 字段类型 是否必须 字段说明
    force_regenerate boolean 是否需要重新生成预览
    kind string 生成的预览图类型,具体类型见该接口的描述

    返回示例

    若预览图未生成:

    {
      "category": "thumbnail",
      "exif_rotation": 0,
      "format": "jpg",
      "has_2048": true,
      "page_count": 0,
      "status": "generating",
      "success": true
    }
    

    若预览图已经生成:

    {
      "category": "thumbnail",
      "download_url": "https://download.fangcloud.net/download/54fd549c300c4173943247c1ef6dbf1e/14bb886708fe0de39151e2f7d2652a26cfefa1704a2fdd2070cb36f46dd37749/99ca1daf0d05eeaaf1b759494d4d9b3b.image_64.jpg",
      "exif_rotation": 1,
      "format": "jpg",
      "has_2048": true,
      "page_count": 1,
      "status": "generated",
      "success": true
    }
    

    若预览图生成失败:

    {
      "status": "failed",
      "representation_fail_reason": "generating_failed",
      "success": true
    }
    

    返回字段说明

    若预览图未生成:

    返回字段 字段类型 字段说明
    category string 预览图的分类
    exif_rotation int 表示图片的旋转,具体可参考https://beradrian.wordpress.com/2008/11/14/rotate-exif-images/
    format string 预览图的后缀名
    has_2048 boolean 是否能生成2048 * 2048的预览图
    page_count int 当page_count大于1时,则不会显示download_url,需要调用获取文件预览转后的下载地址接口做分页下载
    status string 预览转换的状态

    若预览图已经生成,则会在上面的基础上多以下字段:

    返回字段 字段类型 字段说明
    download_url url 预览图的下载链接

    若预览图生成失败:

    返回字段 字段类型 字段说明
    status string 固定为failed
    representation_fail_reason string 预览生成失败的原因

    错误码列表

    获取文件预览转换后的下载地址

    该请求不会触发预览转换,若该文件已经生成预览,则返回下载地址。客户如果在调用上一个预览文件接口时,指定预览转换格式为图片,那么如果返回的page_count大于1的话,则需要调用该接口分页下载转换好的图片。

    URL

    https://open.fangcloud.com/api/file/{id}/preview_download

    HTTP请求方式

    POST

    路径参数

    参数字段 字段类型 字段说明
    id long 文件id

    POST Body

    {
        "page_index": 1,
        "kind": "image_64"
    }
    

    参数说明

    参数字段 字段类型 是否必须 字段说明
    page_index int 分页下载,常用于预览图是多页的情况。从1开始计数,比如共3页的话,那么page_index对应的是1,2,3
    kind string 生成的预览图类型,具体类型见该预览文件接口的描述
    is_attachment boolean 是否附件下载

    返回示例

    {
      "download_url": "https://download.fangcloud.net/download/54fd549c300c4173943247c1ef6dbf1e/14bb886708fe0de39151e2f7d2652a26cfefa1704a2fdd2070cb36f46dd37749/99ca1daf0d05eeaaf1b759494d4d9b3b.image_64.1.jpg",
      "success": true
    }
    

    返回字段说明

    若预览图未生成:

    返回字段 字段类型 字段说明
    success boolean 固定为false

    若预览图已经生成,则会在上面的基础上多以下字段:

    返回字段 字段类型 字段说明
    download_url url 预览图的下载链接

    若预览图生成失败:

    返回字段 字段类型 字段说明
    status string 固定为failed
    representation_fail_reason string 预览生成失败的原因

    错误码列表

    预览嵌入

    若需要在浏览器中展现预览图,并且不想自己实现预览图的加载,那么可以通过iframe的形式嵌入亿方云提供的预览页面。我们分别为PC浏览器(Web)和移动端浏览器(HTML5)提供了各自的预览页面。

    URL

    调用方式

    iframe

    URL参数说明

    参数字段 字段类型 是否必须 字段说明
    access_token string 当前用户的access_token
    file_id long 需要预览的文件的id
    file_name string 需要预览的文件的名称,如果不传递该参数,则会自动调用/file/info来获取file_name

    示例

    <iframe src="https://open.fangcloud.com/preview/preview.html?access_token=xxx&file_id=1&file_name=xxx"></iframe>

    复制文件

    URL

    https://open.fangcloud.com/api/file/copy

    HTTP请求方式

    POST

    POST Body

    {
        "file_id": 1,
        "target_folder_id": 2,
        "is_check_conflict": false
    }
    

    参数说明

    参数字段 字段类型 是否必须 字段说明
    file_id long 被拷贝的文件id
    target_folder_id long 拷贝至的文件夹id
    is_check_conflict boolean 是否检查命名冲突

    如果没有is_check_conflict参数默认会检查命名冲突,如果设置为false并出现命名冲突则会重命名拷贝后的文件(在文件名后增加一串随机字符串)。

    返回示例

    {
      "new_file": {
        "extension": "",
        "created_at": 1466131038,
        "modified_at": 1466131038,
        "owned_by": {
          "id": 6072,
          "name": "测试账号",
          "login": "ceshi@admin.com",
          "enterprise_id": 700
        },
        "description": "",
        "remark": "",
        "id": 41000100000,
        "name": "aaa",
        "typed_id": "file_41000100000",
        "user_id": 6072,
        "size": 1366193,
        "parent_folder_id": 41000000007,
        "in_trash": false,
        "is_deleted": false
      },
      "success": true
    }
    

    返回字段说明

    返回字段 字段类型 字段说明
    new_file file 复制产生的新的file

    错误码列表

    文件夹(FOLDER)操作

    获取文件夹信息

    URL

    https://open.fangcloud.com/api/folder/{id}/info

    HTTP请求方式

    GET

    路径参数

    参数字段 字段类型 字段说明
    id long 文件夹id

    返回示例

    {
      "item_count": 2,
      "folder_type": "normal",
      "type": "folder",
      "id": 711195,
      "name": "新手入门",
      "size": 444984,
      "created_at": 1454218444,
      "modified_at": 1454218444,
      "description": "",
      "path": [
        {
          "type": "folder",
          "id": 0,
          "name": "全部文件"
        }
      ],
      "owned_by": {
        "id": 12030,
        "name": "测试帐号",
        "login": "auto@test.com",
        "enterprise_id": 2411
      },
      "shared": false,
      "parent": {
        "type": "folder",
        "id": 0,
        "name": "全部文件"
      },
      "in_trash": false,
      "is_deleted": false,
      "sequence_id": 0,
      "success": true
    }
    

    返回字段说明

    返回字段 字段类型 字段说明
    item_count int 包含item的数量
    folder_type string 文件夹类型
    type string 固定为"folder"
    id long 文件夹id
    name string 文件夹名称
    size long 文件夹大小
    created_at timestamp 文件夹创建时间,单位为秒
    modified_at timestamp 文件夹更新时间,单位为秒
    description string 文件夹描述
    path folder数组 所有的祖先文件夹
    owned_by user 所有者
    shared boolean 是否被分享,目前都为false
    parent folder 父文件夹
    sequence_id long 目前没有用
    in_trash boolean 是否在回收站中
    is_deleted boolean 是否已经被删除
    success boolean 请求是否成功

    错误码列表

    创建文件夹

    URL

    https://open.fangcloud.com/api/folder/create

    HTTP请求方式

    POST

    POST Body

    {
        "name": "xxx",
        "parent_id": 0
    }
    

    参数说明

    参数字段 字段类型 是否必须 字段说明
    name string 文件夹名
    parent_id long 父文件夹id
    department_id long 在指定部门空间下创建文件夹(仅在parent_id为0情况下生效)

    返回示例

    {
      "item_count": 0,
      "folder_type": "normal",
      "type": "folder",
      "id": 475000032002,
      "name": "xxx",
      "size": 0,
      "created_at": 1466130943,
      "modified_at": 1466130943,
      "description": "",
      "path": [
        {
          "type": "folder",
          "id": 0,
          "name": "全部文件"
        }
      ],
      "owned_by": {
        "id": 12030,
        "name": "测试帐号",
        "login": "auto@test.com",
        "enterprise_id": 2411
      },
      "shared": false,
      "parent": {
        "type": "folder",
        "id": 0,
        "name": "全部文件"
      },
      "in_trash": false,
      "is_deleted": false,
      "sequence_id": 0,
      "success": true
    }
    

    返回字段说明

    返回字段 字段类型 字段说明
    item_count int 包含item的数量
    folder_type string 文件夹类型
    type string 固定为"folder"
    id long 文件夹id
    name string 文件夹名称
    size long 文件夹大小
    created_at timestamp 文件夹创建时间,单位为秒
    modified_at timestamp 文件夹更新时间,单位为秒
    description string 文件夹描述
    path folder数组 所有的祖先文件夹
    owned_by user 所有者
    shared boolean 是否被分享,目前都为false
    parent folder 父文件夹
    sequence_id long 目前没有用
    in_trash boolean 是否在回收站中
    is_deleted boolean 是否已经被删除
    success boolean 请求是否成功

    错误码列表

    更新文件夹

    URL

    https://open.fangcloud.com/api/folder/{id}/update

    HTTP请求方式

    PUT

    POST Body

    {
        "name": "new name"
    }
    

    参数说明

    参数字段 字段类型 是否必须 字段说明
    name string 文件夹名

    返回示例

    {
      "item_count": 0,
      "folder_type": "normal",
      "type": "folder",
      "id": 475000032002,
      "name": "new name",
      "size": 0,
      "created_at": 1466130943,
      "modified_at": 1466132390,
      "description": "",
      "path": [
        {
          "type": "folder",
          "id": 0,
          "name": "全部文件"
        }
      ],
      "owned_by": {
        "id": 12030,
        "name": "测试帐号",
        "login": "auto@test.com",
        "enterprise_id": 2411
      },
      "shared": false,
      "parent": {
        "type": "folder",
        "id": 0,
        "name": "全部文件"
      },
      "in_trash": false,
      "is_deleted": false,
      "sequence_id": 0,
      "success": true
    }
    

    返回字段说明

    返回字段 字段类型 字段说明
    item_count int 包含item的数量
    folder_type string 文件夹类型
    type string 固定为"folder"
    id long 文件夹id
    name string 文件夹名称
    size long 文件夹大小
    created_at timestamp 文件夹创建时间,单位为秒
    modified_at timestamp 文件夹更新时间,单位为秒
    description string 文件夹描述
    path folder数组 所有的祖先文件夹
    owned_by user 所有者
    shared boolean 是否被分享,目前都为false
    parent folder 父文件夹
    sequence_id long 目前没有用
    in_trash boolean 是否在回收站中
    is_deleted boolean 是否已经被删除
    success boolean 请求是否成功

    错误码列表

    删除文件夹至回收站

    支持批量操作

    URL

    https://open.fangcloud.com/api/folder/delete

    HTTP请求方式

    DELETE

    POST Body

    {
        "folder_ids":
            [
                475000032002,
                475000032007
            ]
    }
    

    参数说明

    参数字段 字段类型 是否必须 字段说明
    folder_ids list 文件夹id列表

    返回示例

    {
      "success": true
    }
    

    错误码列表

    从回收站删除文件夹

    支持批量操作

    URL

    https://open.fangcloud.com/api/folder/delete_from_trash

    HTTP请求方式

    DELETE

    POST Body

    仅删除某些文件夹:

    {
        "folder_ids":
            [
                475000032002,
                475000032007
            ]
    }
    

    删除回收站所有文件夹:

    {
        "clear_trash": true
    }
    

    参数说明

    仅删除某些文件夹:

    参数字段 字段类型 是否必须 字段说明
    folder_ids list 文件夹id列表

    删除回收站所有文件夹:

    参数字段 字段类型 是否必须 字段说明
    clear_trash bool 是否需要清空回收站中的文件夹,在此处场景肯定为true

    返回示例

    {
      "success": true
    }
    

    错误码列表

    从回收站恢复文件夹

    支持批量操作

    URL

    https://open.fangcloud.com/api/folder/restore_from_trash

    HTTP请求方式

    POST

    POST Body

    仅恢复某些文件夹:

    {
        "folder_ids":
            [
                475000032002,
                475000032007
            ]
    }
    

    恢复回收站中所有文件夹:

    {
        "restore_all": true
    }
    

    参数说明

    仅恢复某些文件夹:

    参数字段 字段类型 是否必须 字段说明
    folder_ids list 文件夹id列表

    恢复回收站中所有文件夹:

    参数字段 字段类型 是否必须 字段说明
    restore_all bool 是否需要恢复回收站中所有的文件夹,在此处场景肯定为true

    返回示例

    {
      "success": true
    }
    

    错误码列表

    移动文件夹

    支持批量操作

    URL

    https://open.fangcloud.com/api/folder/move

    HTTP请求方式

    POST

    POST Body

    {
        "folder_ids":
            [
                475000032002,
                475000032007
            ],
        "target_folder_id": 475000032006
    }
    

    参数说明

    参数字段 字段类型 是否必须 字段说明
    folder_ids list 文件夹id列表
    target_folder_id long 目标文件夹id
    department_id long 在指定部门空间下创建文件夹(仅在parent_id为0情况下生效)

    返回示例

    {
      "success": true
    }
    

    错误码列表

    获取单层子文件和文件夹列表

    URL

    https://open.fangcloud.com/api/folder/children

    HTTP请求方式

    GET

    URL参数

    参数字段 字段类型 是否必须 字段说明
    folder_id long 文件夹id
    department_id long 指定部门空间,只在folder_id为0的情况下生效
    page_id int 页号
    page_capacity int 页容量
    type string 分为file,folder,all三种,默认为all

    返回示例

    {
      "files": [
        {
          "extension_category": "",
          "comments_count": 0,
          "type": "file",
          "id": 81158,
          "name": "成绩单.pdf",
          "size": 481980,
          "created_at": 1409816198,
          "modified_at": 1464686224,
          "description": "",
          "shared": false,
          "in_trash": false,
          "is_deleted": false,
          "sequence_id": 0
        },
        {
          "extension_category": "",
          "comments_count": 0,
          "type": "file",
          "id": 81503,
          "name": "3-通讯录 (4).xlsx",
          "size": 12368,
          "created_at": 1409884838,
          "modified_at": 1409884839,
          "description": "",
          "shared": false,
          "in_trash": false,
          "is_deleted": false,
          "sequence_id": 0
        },
        {
          "extension_category": "",
          "comments_count": 0,
          "type": "file",
          "id": 81504,
          "name": "【亿方云科技】公司战略 (3).pptx",
          "size": 2430649,
          "created_at": 1409884859,
          "modified_at": 1409884860,
          "description": "",
          "shared": false,
          "in_trash": false,
          "is_deleted": false,
          "sequence_id": 0
        },
        {
          "extension_category": "",
          "comments_count": 0,
          "type": "file",
          "id": 81505,
          "name": "竞争对手分析 (3).docx",
          "size": 17177,
          "created_at": 1409884943,
          "modified_at": 1409884944,
          "description": "",
          "shared": false,
          "in_trash": false,
          "is_deleted": false,
          "sequence_id": 0
        },
        {
          "extension_category": "",
          "comments_count": 0,
          "type": "file",
          "id": 81506,
          "name": "App.java",
          "size": 1490,
          "created_at": 1409884977,
          "modified_at": 1409884978,
          "description": "",
          "shared": false,
          "in_trash": false,
          "is_deleted": false,
          "sequence_id": 0
        },
        {
          "extension_category": "",
          "comments_count": 0,
          "type": "file",
          "id": 81507,
          "name": "1.jpg",
          "size": 19181,
          "created_at": 1409885238,
          "modified_at": 1409885239,
          "description": "",
          "shared": false,
          "in_trash": false,
          "is_deleted": false,
          "sequence_id": 0
        },
        {
          "extension_category": "",
          "comments_count": 0,
          "type": "file",
          "id": 81508,
          "name": "1 (1).jpg",
          "size": 19181,
          "created_at": 1409885270,
          "modified_at": 1409885271,
          "description": "",
          "shared": false,
          "in_trash": false,
          "is_deleted": false,
          "sequence_id": 0
        },
        {
          "extension_category": "",
          "comments_count": 0,
          "type": "file",
          "id": 81509,
          "name": "App (1)xx.java",
          "size": 1490,
          "created_at": 1409885278,
          "modified_at": 1410225765,
          "description": "",
          "shared": false,
          "in_trash": false,
          "is_deleted": false,
          "sequence_id": 0
        }
      ],
      "folders": [
        {
          "item_count": 0,
          "type": "folder",
          "id": 110124,
          "name": "syj_aaa",
          "size": 34831941,
          "created_at": 1438668938,
          "modified_at": 1439781981,
          "description": "",
          "shared": true,
          "in_trash": false,
          "is_deleted": false,
          "sequence_id": 0
        },
        {
          "item_count": 0,
          "type": "folder",
          "id": 111970,
          "name": "aaa (8)",
          "size": 782,
          "created_at": 1438851543,
          "modified_at": 1439261080,
          "description": "",
          "shared": false,
          "in_trash": false,
          "is_deleted": false,
          "sequence_id": 0
        }
      ],
      "total_count": 1065,
      "page_id": 1,
      "page_capacity": 10,
      "success": true
    }
    

    返回字段说明

    返回字段 字段类型 字段说明
    folders list 包含的folder的list
    files list 包含的file的list
    total_count int 所有item的数量
    page_id int 页号
    page_capacity int 页容量

    文件或文件夹(ITEM)操作

    搜索

    URL

    https://open.fangcloud.com/api/item/search

    HTTP请求方式

    GET

    URL参数说明

    参数字段 字段类型 是否必须 字段说明
    query_words string 搜索关键词
    type string 搜索类型,分为file,folder,all三种,默认为all
    page_number int 第几页,每页默认20,默认为第0页
    search_in_folder int 指定父文件夹,匹配的结果都是该文件夹的子文件或子文件夹
    query_filter string 搜索过滤类型,分为file_name,content,all三种,默认为all

    返回示例

    {
      "files": [
        {
          "extension_category": "",
          "comments_count": 0,
          "type": "file",
          "id": 1949531,
          "name": "test001.fangnote",
          "size": 334,
          "created_at": 1450247921,
          "modified_at": 1450341414,
          "description": "",
          "shared": false,
          "in_trash": false,
          "is_deleted": false,
          "sequence_id": 0
        }
      ],
      "folders": [
        {
          "item_count": 0,
          "type": "folder",
          "id": 245799,
          "name": "annotations",
          "size": 30512,
          "created_at": 1443519500,
          "modified_at": 1444802325,
          "description": "",
          "shared": false,
          "in_trash": false,
          "is_deleted": false,
          "sequence_id": 67
        },
        ......
      ],
      "total_count": 1856,
      "page_id": 0,
      "page_capacity": 20,
      "success": true
    }
    

    返回字段说明

    返回字段 字段类型 字段说明
    folders list 搜索到的folder的list
    files list 搜索到的file的list
    total_count int 所有匹配结果的数量
    page_id int 页号,从0开始
    page_capacity int 页容量

    用户(User)操作

    获取用户的as_user码

    此接口为高级接口,常用于跨用户传输文件,若需使用需联系客服

    获取自身用户信息

    URL

    https://open.fangcloud.com/api/user/info

    HTTP请求方式

    GET

    返回示例

    {
      "id": 449,
      "enterprise_id": 89,
      "name": "qyang1",
      "phone": "15088679770",
      "email": "qyang1@admin.com",
      "profile_pic_key": "f2b7154b8fa0500004fa0cde46e5e214",
      "active": true,
      "full_name_pinyin": "qyang1",
      "pinyin_first_letters": "qyang1",
      "success": true
    }
    

    返回字段说明

    返回字段 字段类型 字段说明
    id long 用户id
    enterprise_id long 企业id
    name string 用户姓名
    phone string 用户手机
    email string 用户邮箱
    profile_pic_key string 用户头像下载所需的key
    active boolean 用户是否激活
    full_name_pinyin string 用户姓名的拼音字母
    pinyin_first_letters string 用户姓名的拼音首字母

    获取他人用户信息

    URL

    https://open.fangcloud.com/api/user/{id}/info

    HTTP请求方式

    GET

    路径参数

    参数字段 字段类型 字段说明
    id long 被查看者用户id

    返回示例

    {
      "id": 449,
      "enterprise_id": 89,
      "name": "qyang1",
      "phone": "15088679770",
      "email": "qyang1@admin.com",
      "profile_pic_key": "f2b7154b8fa0500004fa0cde46e5e214",
      "active": true,
      "full_name_pinyin": "qyang1",
      "pinyin_first_letters": "qyang1",
      "success": true
    }
    

    返回字段说明

    返回字段 字段类型 字段说明
    id long 用户id
    enterprise_id long 企业id
    name string 用户姓名
    phone string 用户手机
    email string 用户邮箱
    profile_pic_key string 用户头像下载所需的key
    active boolean 用户是否激活
    full_name_pinyin string 用户姓名的拼音字母
    pinyin_first_letters string 用户姓名的拼音首字母

    错误码列表

    下载用户头像

    URL

    https://open.fangcloud.com/api/user/profile_pic_download

    HTTP请求方式

    GET

    URL参数说明

    参数字段 字段类型 是否必须 字段说明
    user_id long 搜索关键词
    profile_pic_key string 下载头像所需的key

    该接口的返回结果是一个头像文件

    错误码列表

    通用对象

    File

    字段 类型 说明
    id long 文件id
    user_id long 所有者id
    size long 文件大小
    parent_folder_id long 父文件夹id
    name string 文件名
    extension string 文件扩展名
    extension_category string 文件扩展名的分类
    description string 文件描述
    remark string 文件备注
    typed_id string file + "_" + id
    owned_by user 所有者对象
    created_at timestamp 文件创建时间
    modified_at timestamp 文件修改时间
    in_trash boolean 是否在回收站中
    is_deleted boolean 是否已经被删除

    Folder

    字段 类型 说明
    item_count int 包含item的数量
    folder_type string 文件夹类型
    type string 固定为"folder"
    id long 文件夹id
    name string 文件夹名称
    size long 文件夹大小
    created_at timestamp 文件夹创建时间,单位为秒
    modified_at timestamp 文件夹更新时间,单位为秒
    description string 文件夹描述
    path folder数组 所有的祖先文件夹
    owned_by user 所有者
    shared boolean 是否被分享,目前都为false
    parent folder 父文件夹
    sequence_id long 目前没有用
    in_trash boolean 是否在回收站中
    is_deleted boolean 是否已经被删除

    User

    字段 类型 说明
    id long 用户id
    enterprise_id long 企业id
    name string 用户姓名
    phone string 用户手机
    email string 用户邮箱
    profile_pic_key string 用户头像下载所需的key
    active boolean 用户是否激活
    full_name_pinyin string 用户姓名的拼音字母
    pinyin_first_letters string 用户姓名的拼音首字母

    其他

    更多接口以及接口详情可参考: https://www.fangcloud.com/share/4c1f1f4a1ff20295966b7fe686

    异常处理

    异常格式

    api接口的异常格式如右所示:

    {
      "errors": [
        {
          "msg": "文件不存在",
          "code": "file_not_found"
        }
      ],
      "request_id": "fdjklsa-asdrwer2312314q-asdfasfav-falsfdjas"
    }
    

    错误码

    code message
    permission_denied 权限不足
    file_not_found 文件不存在
    folder_not_found 文件夹不存在
    file_deleted 文件已删除
    folder_deleted 文件夹已删除
    file_in_trash_not_found 文件不在回收站
    folder_in_trash_not_found 文件夹不在回收站
    file_name_conflict 文件命名冲突
    folder_name_conflict 文件夹命名冲突
    folder_empty_in_trash 回收站无文件夹
    folder_parent_deleted 父文件夹已被删除
    item_name_invalid 文件或文件夹名称不合法
    item_name_size_incorrect 文件或文件夹名称长度错误
    request_data_invalid 请求参数错误
    exceed_enterprise_space_limit 超过企业空间限制
    exceed_user_space_limit 超过用户空间限制
    folder_is_descendant 目标文件夹是移动文件夹的子目录
    user_not_found 用户不存在
    user_profile_pic_not_found 用户头像不存在
    user_profile_pic_key_not_found 用户头像的key未传入
    user_profile_pic_key_incorrect 用户头像的key与user_id不匹配

    ps: