接口认证
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:
- Authorization:存放access_token,格式为:"Bearer " + access_token。
- Content-Type:指明请求参数的格式。如果是POST、PUT或者DELETE请求,需要指定"application/json",我们目前不支持其他请求参数的格式,比如xml。如果是其他类型比如GET请求,可以不在header中设置Content-Type。
- Accept:用于指定响应结果的格式以及api的版本信息。目前只支持返回json格式的response,所以一般情况下指定"application/json"。
若接口访问成功,我们会返回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 | 请求是否成功 |
错误码列表
- file_not_found
- file_deleted
- permission_denied
更新文件信息
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 | 请求是否成功 |
错误码列表
- file_not_found
- file_deleted
- permission_denied
- request_data_invalid
- file_name_conflict
- item_description_size_incorrect
删除文件至回收站
支持批量操作
URL
https://open.fangcloud.com/api/file/delete
HTTP请求方式
DELETE
POST Body
{
"file_ids": [4063821, 85723]
}
参数说明
参数字段 | 字段类型 | 是否必须 | 字段说明 |
---|---|---|---|
file_ids | long数组 | 是 | 文件id |
返回示例
{
"success": true
}
返回字段说明
无
错误码列表
- file_not_found
- permission_denied
- file_deleted
- request_data_invalid
从回收站删除文件
支持批量操作
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
}
返回字段说明
无
错误码列表
- file_not_found
- permission_denied
- file_deleted
- file_empty_in_trash
- request_data_invalid
从回收站恢复文件
支持批量操作
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
}
返回字段说明
无
错误码列表
- file_in_trash_not_found
- folder_parent_deleted
- file_empty_in_trash
- request_data_invalid
移动文件
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
}
返回字段说明
无
错误码列表
- file_not_found
- file_deleted
- permission_denied
- request_data_invalid
- folder_not_found
获取新文件上传地址
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个小时,且只能被使用一次 |
错误码列表
- item_name_invalid
- item_name_size_incorrect
- folder_not_found
- permission_denied
- request_data_invalid
获取文件上传新版本地址
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个小时,且只能被使用一次 |
错误码列表
- item_name_invalid
- item_name_size_incorrect
- file_not_found
- permission_denied
- request_data_invalid
文件上传
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个小时,且只能被使用一次 |
错误码列表
- item_not_found_or_deleted
- permission_denied
预览文件
分为发起预览请求和得到当前预览转换的进度,如果当前的进度为预览转换成功,则会得到预览文件的下载地址。
我们可转换成的预览类型有:
- image_64:表示像素64 * 64的图片,常用于缩略图
- image_128:表示像素128 * 128的图片,常用于缩略图
- image_1024:表示像素1024 * 1024的图片,标准预览格式
- image_2048:表示像素2048 * 2048的图片,常用于高清图
- pdf:表示pdf文件
每种预览类型支持的文件格式如下:
预览类型 | 支持的文件格式 |
---|---|
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 |
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 | 预览生成失败的原因 |
错误码列表
- file_not_found
- file_deleted
- permission_denied
- request_data_invalid
获取文件预览转换后的下载地址
该请求不会触发预览转换,若该文件已经生成预览,则返回下载地址。客户如果在调用上一个预览文件接口时,指定预览转换格式为图片,那么如果返回的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 | 预览生成失败的原因 |
错误码列表
- file_not_found
- file_deleted
- permission_denied
- request_data_invalid
预览嵌入
若需要在浏览器中展现预览图,并且不想自己实现预览图的加载,那么可以通过iframe的形式嵌入亿方云提供的预览页面。我们分别为PC浏览器(Web)和移动端浏览器(HTML5)提供了各自的预览页面。
URL
- 默认形式如WEB:https://open.fangcloud.com/preview/preview.html
- HTML5:https://open.fangcloud.com/preview/preview-mobile.html
调用方式
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_not_found
- folder_deleted
- file_not_found
- file_deleted
- permission_denied
- file_in_final_storage_not_found
- request_data_invalid
文件夹(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 | 请求是否成功 |
错误码列表
- permission_denied
- folder_not_found
- folder_deleted
创建文件夹
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 | 请求是否成功 |
错误码列表
- permission_denied
- folder_name_conflict
- folder_not_found
- item_name_invalid
- filed_required
更新文件夹
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 | 请求是否成功 |
错误码列表
- permission_denied
- folder_not_found
- folder_deleted
- folder_name_conflict
- request_data_invalid
删除文件夹至回收站
支持批量操作
URL
https://open.fangcloud.com/api/folder/delete
HTTP请求方式
DELETE
POST Body
{
"folder_ids":
[
475000032002,
475000032007
]
}
参数说明
参数字段 | 字段类型 | 是否必须 | 字段说明 |
---|---|---|---|
folder_ids | list | 是 | 文件夹id列表 |
返回示例
{
"success": true
}
错误码列表
- request_data_invalid
- permission_denied
- folder_not_found
- folder_deleted
从回收站删除文件夹
支持批量操作
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
}
错误码列表
- request_data_invalid
- filed_required
- permission_denied
- folder_not_found
- folder_deleted
- folder_in_trash_not_found
- folder_empty_in_trash
从回收站恢复文件夹
支持批量操作
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
}
错误码列表
- request_data_invalid
- filed_required
- permission_denied
- folder_empty_in_trash
- folder_not_found
- folder_deleted
- folder_parent_deleted
- exceed_enterprise_space_limit
- exceed_user_space_limit
移动文件夹
支持批量操作
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
}
错误码列表
- permission_denied
- folder_not_found
- folder_deleted
- folder_is_descendant
- request_data_invalid
获取单层子文件和文件夹列表
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 | 用户手机 |
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 | 用户手机 |
string | 用户邮箱 | |
profile_pic_key | string | 用户头像下载所需的key |
active | boolean | 用户是否激活 |
full_name_pinyin | string | 用户姓名的拼音字母 |
pinyin_first_letters | string | 用户姓名的拼音首字母 |
错误码列表
- permission_denied
- user_not_found
下载用户头像
URL
https://open.fangcloud.com/api/user/profile_pic_download
HTTP请求方式
GET
URL参数说明
参数字段 | 字段类型 | 是否必须 | 字段说明 |
---|---|---|---|
user_id | long | 是 | 搜索关键词 |
profile_pic_key | string | 是 | 下载头像所需的key |
该接口的返回结果是一个头像文件
错误码列表
- permission_denied
- user_not_found
- user_profile_pic_key_not_found
- user_profile_pic_key_incorrect
- user_profile_pic_not_found
通用对象
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 | 用户手机 |
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:
- 用户传入的json格式错误,返回invalid_error
- json中缺少required字段,返回filed_required,并在msg中提示缺少的字段
- 其他入餐错误,返回 request_data_invalid