亿方云开放平台是基于亿方云基础业务和功能向开发者提供二次开发的服务平台，为企业提供丰富的云盘文档协同管理解决方案。企业或第三方合作伙伴可以快速低成本地接入亿方云，实现存储、查看、分享、协作等一站式文件管理。激活企业非结构数据资产价值，助你的企业更快一步。

亿方云开放平台提供UI组件、SDK、API等接入方式，10行代码助你构建企业文件统一管理平台。

亿方云的开放平台，是在云计算背景下，将亿方云已有的能力通过多种形式开放给第三方开发者使用，而产生的一种技术能力输出。开放平台所有功能基于亿方云已有功能，并不断迭代，基于安全角度考虑，所有能力输出将严格依照Oauth2协议进行授权和鉴权。

其中核心能力为接入层的代理服务、Oauth鉴权服务、Open API能力输出。代理服务主要提供访问接入底层服务，以WEB方式实现。Oauth鉴权服务通过Oauth协议对接入者进行授权和鉴权，返回相应的access_token信息，该token具备时效性，可有效保障接入安全和数据安全。Open API即为亿方云能力输出相关API，目前已开放近100个API，涉及文件（夹）管理、分享、协作、日志、消息、第三方同步等大量功能，可有效辅助开发者接入开放平台。

在此基础上，为便于开发者接入亿方云开放平台，还提供了WEB、H5的UI组件，涉及文件选择、文件上传、文件预览等基础能力，开发者无需再去构建文件显示、列表等基本架构。

• 企业内部开发

  企业依托亿方云强大的开放能力，将亿方云文件存储与共享的能力接入到企业自身的HR、OA、客户管理、业务管理等系统，实现文件的统一存储和协作。

• access_token

  1.access_token是访问亿方云服务端开放接口的全局唯一凭证。

  2.正常情况下access_token有效期为6小时。

• client_id

  client_id是企业接入亿方云开放平台的唯一性标识。开发者在申请开放平台应用时，系统会自动生成。

• client_secret

  client_secret和client_id在企业申请开放平台时一同生成，使用client_id和client_secret可获取access_token。

• 回调

  企业在申请亿方云开放平台时，可为应用设置一个URL。一些应用相关的重要事件发生时，亿方云向该URL地址发起http请求，此URL称之为回调地址。

• 免登

  “免登”是指用户免除输入亿方云用户名和密码，应用便可获取用户身份，登录亿方云。

• 应用专属账号

  员工在使用企业内部应用的过程中，可将从本地上传或者从亿方云选择的文件保存到应用专属账号。企业内部应用将员工所上传的文件存储在应用专属账号中，可以控制用户预览、保存至亿方云、下载等权限，也可以将员工账号添加为文件夹的协作权限来授予员工相应的访问权限。

第一步：申请开放平台

目前亿方云开放平台需要申请才能开放，具体的申请可直接拨打我司客服热线：400-993-9050。具体步骤开发者需要在企业控制台（只有企业管理员或联合管理员才能进入）里面申请应用，企业控制台-企业设置-开放平台中设置相关信息提交应用，待应用审核通过后即可进入第二步。

第二步：接口认证，获取授权

当审核通过后，则会分配一个client_id和client_secret应用审核通过后会获得该应用的client_id和client_secret，拿到这两个信息即可进行接口认证，获取相关的接口认证。

第三步：应用开发

接口认证获取授权后，即可调用亿方云提供的API、SDK、UI组件。

企业级token

只能请求企业级API（路径中含有admin），示例如下：

{
   "access_token":"8afa8c99-4490-4f64-a3ce-ebfda52d893a",
   "refresh_token":"70903bbd-9825-4ef2-b967-0c6ae0fb0946",
   "scope":"admin",
   "token_type":"bearer",
   "expires_in":21599
}

用户级token

只能请求用户级API，示例如下：

{
   "access_token":"7e40bd40-080f-4131-ba8b-7f6ce5ac0a83",
   "refresh_token":"98db229d-1a76-4491-b2c7-37be7f37dcaf",
   "scope":"all",
   "token_type":"bearer",
   "expires_in":21599
}

第一步：获取相关参数

向云盘工作人员获取企业id，开放平台的client_id和client_secret参数

第二步：生成请求header

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

第三步：生成请求参数

组装map集合，map集合参数如下：

组装完成的map集合示例：

 {
    "sub": "21791",
    "yifangyun_sub_type": "enterprise",
    "exp": "1725590139",
    "iat": "1725590079",
    "jti": "17255900799152711bfbc-435f-45b6-a8d4-6e750e14b005"
 }

将组装好的map转成字符串并其进行：Base64Encode，生成assertion参数，转换完成的assertion示例：

 ewogICAgInN1YiI6ICIyMTc5MSIsCiAgICAieWlmYW5neXVuX3N1Yl90eXBlIjogImVudGVycHJpc2UiLAogICAgImV4cCI6ICIxNzI1NTkwMTM5IiwKICAgICJpYXQiOiAiMTcyNTU5MDA3OSIsCiAgICAianRpIjogIjE3MjU1OTAwNzk5MTUyNzExYmZiYy00MzVmLTQ1YjYtYThkNC02ZTc1MGUxNGIwMDUiCn0=

第四步：请求获取token

HTTP请求方式： POST URL参数：

请求示例：

 curl --location --request POST 'https://oauth.fangcloud.net/oauth/token?grant_type=jwt_simple&assertion=ewogICAgInN1YiI6ICIyMTc5MSIsCiAgICAieWlmYW5neXVuX3N1Yl90eXBlIjogImVudGVycHJpc2UiLAogICAgImV4cCI6ICIxNzI1NTkwMTM5IiwKICAgICJpYXQiOiAiMTcyNTU5MDA3OSIsCiAgICAianRpIjogIjE3MjU1OTAwNzk5MTUyNzExYmZiYy00MzVmLTQ1YjYtYThkNC02ZTc1MGUxNGIwMDUiCn0=' 
 --header 'Authorization: Basic M2RjMjcyNjQtMGJhNi00ZjQ3LWI3ZGUtNjhiNWFhNWFiZDQxOjA1MmQ4YjAzLWRiNTEtNDM3Ni04ZTA1LTZhNmU1NWNlNGMzMA==' 

获取用户信息API接口地址

根据接口返回用户信息中的用户id，可以生成对应的用户token

请求示例

curl --location 'https://open.fangcloud.com/api/v2/admin/user/get_user_info?identifier=18888888888@test.com&type=simple_phone_or_email' \
--header 'Authorization: Bearer 021ae7ad-a803-49d8-a070-52b84e6c0705' 

postman请求示例

package com.example.liangxiaoshengdemo.token.simple_jwt; 
 
import com.alibaba.fastjson.JSON; 
import com.alibaba.fastjson.JSONObject; 
import org.apache.http.HttpEntity; 
import org.apache.http.HttpResponse; 
import org.apache.http.client.methods.HttpPost; 
import org.apache.http.impl.client.DefaultHttpClient; 
import org.apache.http.util.EntityUtils; 
import java.util.*; 
 
public class DemoSimple { 
 
    static String clientId = ""; 
    static String clientSecret = ""; 
 
    // jwt密钥文件中的enterprise_id，生成企业token使用 
    static long enterpriseId = 0L; 
    // jwt密钥文件中的platform_id 
    static long platformId = 0L; 
    // 用户id，通过接口获取，生成个人token使用 
    static long userId = 0L; 
    // 开放平台获取token地址(专有云需要修改) 
    static String oauthHost = "https://oauth.fangcloud.com"; 
 
    public static void main(String[] args) throws Exception { 
 
        // 生成企业token 
        JSONObject accessTokenAdmin= getAccessToken(oauthHost, clientId, clientSecret, enterpriseId, false); 
        System.out.println("accessTokenAdmin" + JSON.toJSONString(accessTokenAdmin)); 
        // 生成个人token 
        JSONObject accessTokenUser = getAccessToken(oauthHost, clientId, clientSecret, userId, true); 
        System.out.println("accessTokenUser" + JSON.toJSONString(accessTokenUser)); 
  } 
 
    public static JSONObject getAccessToken (String oauthUrl, String appKey, String appSecret, Long id, Boolean isUser) { 
        try{ 
             Map<String, String> dataMap = new HashMap<>(); 
             String yifangyun_sub_type = ""; 
             if (isUser) { 
                yifangyun_sub_type = "user"; 
              } else { 
               yifangyun_sub_type = "enterprise"; 
             } 
 
             dataMap.put("yifangyun_sub_type", yifangyun_sub_type); //授权对象类型   enterprise为企业   user为用户 
             dataMap.put("sub", String.valueOf(id)); //如果授权对象类型为企业 这里输入企业id，如果授权对象类型为user这边输入userid 
             dataMap.put("exp", String.valueOf(getExpirationTimeSecondsInTheFuture(60).getTime()/1000));//过期时间戳，不能超过iat(若iat不存在则记请求到达服务器时间)60s 
             dataMap.put("iat", String.valueOf(new Date().getTime()/1000));//当前 时间 
             dataMap.put("jti", System.currentTimeMillis() + UUID.randomUUID().toString());//随机字符串 
 
             String dataJson = JSON.toJSONString(dataMap); 
             String encodeJson = Base64.getEncoder().encodeToString(dataJson.getBytes()); 
             return getToken(encodeJson, oauthUrl, appKey, appSecret); 
        }catch (Exception e){ 
             e.printStackTrace(); 
        } 
        return null; 
    } 
 
 
    /** 
    * 获取token 
    * @param compactJwt jwt字符串 
    * @param oauthUrl 接口地址 
    * @param appKey client_id 
    * @param appSecret client_secret 
    * @return 返回接口token 
    */ 
    private static JSONObject getToken(String compactJwt, String oauthUrl, String appKey, String appSecret){ 
          String res = ""; 
          DefaultHttpClient httpclient; 
          try { 
                httpclient = new DefaultHttpClient();//https请求 存在证书问题，通过此方式信任所有证书 
 
                String url = oauthUrl + "/oauth/token?grant_type=jwt_simple&assertion=" + compactJwt; 
                System.out.println(url); 
                HttpPost httppost = new HttpPost(url); 
 
                String client = appKey + ":" + appSecret;  //组装client_id和client_secret 
                byte[] bytes = client.getBytes(); 
                String base64Client = Base64.getEncoder().encodeToString(bytes);//base64加密 
                System.out.println(base64Client); 
                httppost.addHeader("Authorization","Basic "+base64Client); 
                HttpResponse response = httpclient.execute(httppost); 
 
                HttpEntity entity = response.getEntity(); 
                res = EntityUtils.toString(entity); 
                return JSONObject.parseObject(res); 
 
          }catch (Exception e){ 
                e.printStackTrace(); 
                return null; 
          } 
    } 
 
    private static Date getExpirationTimeSecondsInTheFuture(int seconds) { 
          Calendar calendar = Calendar.getInstance(); 
          calendar.setTime(new Date()); 
          calendar.add(Calendar.SECOND, seconds); 
          return calendar.getTime(); 
    } 
} 

import hashlib 
import json 
import random 
import time 
import base64 
import requests 
 
# jwt密钥文件中的enterprise_id，生成企业token使用 
enterprise_id = 123 
# 用户id，通过接口获取，生成个人token使用 
user_id = 0 
# jwt密钥文件中的client_id 
client_id = "xxxx" 
# jwt密钥文件中的client_secret 
client_secret = "xxxx" 
# 开放平台获取token地址(专有云需要修改) 
oauth_url = 'https://oauth.fangcloud.com' 
# 开放平台api地址(专有云需要修改) 
open_url = 'https://open.fangcloud.com' 
 
class Test(): 
 
  def jwt_token(id, type): 
 
    jti = "".join(random.sample('abcdefghijklmnopqrstuvwxyz!@#$%^&*1234567890', 16)).replace(' ', '') 
    m = hashlib.md5() 
    m.update(jti.encode("utf-8")) 
    jti_md5 = m.hexdigest() 
    sub_type = '' 
    if(type == 'enterprise'): 
      sub_type = "enterprise" 
    elif(type == 'user'): 
      sub_type = "user" 
 
    payload = { 
    "yifangyun_sub_type": sub_type, 
    "sub": id, 
    "exp": int(time.time()) + 60, 
    "iat": int(time.time()), 
    "jti": jti_md5, 
    } 
 
    headers = { 
    'Authorization': 'Basic '+ base64.b64encode((client_id + ":" + client_secret).encode('utf-8')).decode('ascii') 
    } 
 
    url = oauth_url + '/oauth/token?grant_type=jwt_simple&assertion=' + base64.b64encode(json.dumps(payload).encode('utf-8')).decode('ascii') 
    return requests.post(url, headers=headers).text 
 
  enterprise_token = jwt_token(enterprise_id, 'enterprise') 
  print('enterprise_token:' + enterprise_token) 
  user_token = jwt_token(user_id, 'user') 
  print('user_token:' + user_token) 

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

curl --location --request GET 'https://open.fangcloud.com/api/v2/admin/user/all?platform_id=1&page_id=0&page_capacity=10' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 76ebc21a-e52e-4800-9ada-a1cdd2f77856' 

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

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

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

异常格式

api接口的异常返回可以分为两类，参数验证错误和业务错误

参数验证错误的返回如又所示:

{
   "errors": [
       {
           "msg": "不能为空",
           "code": "request_data_invalid",
           "field": "folder_id"
       }
   ],
   "request_id": "fdjklsa-asdrwer2312314q-asdfasfav-falsfdjas"
}

参数验证错误有统一的错误码request_data_invalid，具体错误信息会在msg中提示，field提示错误的字段

常见的错误msg包括:

• 不能为null
• 不能为空
• 不能包含null
• 最小不能小于{value}
• 长度需要在{min}和{max}之间
• 个数必须在{min}和{max}之间

业务错误的异常格式如下所示：

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

{
   "errors": [
       {
           "msg": "不能为空",
           "code": "request_data_invalid",
           "field": "folder_id"
       }
   ],
   "request_id": "fdjklsa-asdrwer2312314q-asdfasfav-falsfdjas"
}

业务错误通常以不同的code来进行区分

错误码

• 用户传入的json格式错误，返回invalid_error