接口认证
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