开放平台-文档

1接口规范

1.1通信协议

平台采用HTTPS协议跟第三方应用交互，建议以POST方式请求，返回结果为JSON格式。

所有请求和响应数据编码皆为utf-8格式，请求的Content-Type请使用application/x-www-form-urlencoded。

1.2公共请求头参数

通用请求头（Headers）：

字段标识	说明	数据类型	可空
X-Request-ID	唯一值，随机生成，建议uuid	String	N

1.3公共请求body参数

通用请求体（body）：

字段标识	说明	数据类型	可空
appKey	申请应用时分配的应用ID（APPID）	String	N
timeStamp	时间戳，单位毫秒	Long	N
accessToken	获取accessToken接口返回的accessToken	Long	除获取accessToken接口外，其余都不能为空
paras	使用XXTea加密方式对接口定义的所有参数（除appKey,timeStamp,accessToken,sign）拼接后的字符串加密，如params=XXTea((e189AccessToken=xxx&参数2=xxx), appSecret)，其中appSecret是申请应用时平台生成的应用秘钥，参数拼接无顺序要求。	1024	N
sign	sign参数是对除sign外其他参数的RSA加密值，加密算法如下：sign=RSA(accessToken+appKey+paras+timeStamp, RSA_Private_key) 需要注意参数拼接key升序排序。其中RSA_Private_key是合作方的RSA私钥，合作方需要向开放平台提供RSA公钥，（请在“管理中心--我的应用--查看详情”中进行配置），公钥格式要求为：1024bit pkcs#8 格式，用于访问接口时的验签。具体rsa加密获得sign请查看https://id.dlife.cn/api?initialSrc=/html/api_detail_622.html中的RSAUtil和XXTeaUtil	1024	N

2获取云盘AccessToken接口

接口描述	获取云盘AccessToken接口
承载协议	HTTPS
承载网络	公网
请求方式	POST
数据格式	application/x-www-form-urlencoded;响应数据以json格式返回
接口URL	https://api.cloud.189.cn/newOpen/oauth2/accessToken.action

请求头：

字段标识	说明	数据类型	可空
X-Request-ID	唯一值，随机生成，建议uuid	String	N

请求参数：

字段标识	说明	数据类型	可空
appKey	申请应用时分配的应用ID（APPID）	String	N
e189AccessToken	天翼账号AccessToken	String	N

最终请求body请参考通用请求体，所有的接口都是同样的body格式，包含加密及加密顺序要求，上述请求参数中e189AccessToken参数则需要xxtea加密为paras字段参数。

响应参数：

字段标识	说明	数据类型	可空
accessToken	云盘AccessToken	String	N
expiresIn	accesstoken有效期时间，unix timestamp毫秒级，在此时间戳之前，token有效	String	N
refreshToken	用于刷新accessToken	String	Y

示例：

请求（代码参考附录1的getAccessToken方法）：

curl --location --request POST
'https://api.cloud.189.cn/newOpen/oauth2/accessToken.action' \
--header 'X-Request-ID: zsd' \
--header 'User-Agent: Apifox/1.0.0 (https://apifox.com)' \
--header 'Accept: */*' \
--header 'Host: api.cloud.189.cn' \
--header 'Connection: keep-alive' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'appKey=test' \
--data-urlencode 'timeStamp=1695871964000' \
--data-urlencode 'paras=6ca79f2fd283ecda15c77081938f70b5c39f4bd6ec5bfde4' \
--data-urlencode 'sign=AF45794DF68082FD9846FE814CCFA9F9BE1E4877C3624B9B8EF9DF123A20013A7F3063D95817A4ADDA6A43728E08D44E48AF85BB96F4BC060875548D46C976FE904C3D41A4EA6ABF7ED44D4068144DD112195698850345C6ACE4C8D94BBB9161FE49FB2374A09823FE90357C18279A20BF177354478EF37BF0294E04001F4D20'

响应：

正常（状态码200）：
{
"expiresIn": 1636619292643,
"accessToken": "3398222FD0070FCF657A6889CA4DB11A"
}
异常（状态码400）：
{
"res_message": "Internal error",
"res_code": "InternalError"
}

3错误码

3.1常用错误码列表

错误码	描述	HTTP状态码
AccessDenyOfHighFrequency	由于访问频率过高，拒绝访问	400 Bad Request
ErrorDownloadFileNotFound	下载时文件不存在	400 Bad Request
ErrorDownloadFileDeleted	下载时文件已被删除	400 Bad Request
ErrorDownloadFileInvalidParam	下载时无效的下载参数	400 Bad Request
ErrorDownloadFileInternalError	下载时内部错误	400 Bad Request
ErrorDownloadFileInvalidSessionKey	下载时无效的sessionKey	下载时无效的sessionKey
ErrorDownloadFileShareTimeOut	下载时分享文件超时	400 Bad Request
FileAlreadyExists	文件或文件夹已存在	400 Bad Request
FileNotFound	文件或文件夹不存在	400 Bad Request
FileTooLarge	上传文件超过最大限制	400 Bad Request
InsufficientStorageSpace	剩余存储空间不足	400 Bad Request
InternalError	内部错误	500 Internal Server Error
InvalidArgument	非法参数	400 Bad Request
InvalidPassword	密码不正确	400 Bad Request
InvalidParentFolder	无效的父目录	400 Bad Request
InvalidSessionKey	非法登录会话Key	400 Bad Request
InvalidSignature	非法签名	400 Bad Request
MoveFileValidError	文件移动类型检查错误	400 Bad Request
MyIDQRCodeNotLogin	MyID二维码未登录	400 Bad Request
MyIDSignatureVerfiyFailed	MyID数字签名验证失败	400 Bad Request
NoSuchUser	用户账号不存在	400 Bad Request
ParentNotFolder	父文件夹类型不正确	400 Bad Request
PermissionDenied	访问权限不足	400 Bad Request
QRCodeNotBind	二维码未绑定	400 Bad Request
QRCodeNotFound	二维码不存在	400 Bad Request
ServiceNotOpen	云存储服务尚未开通	400 Bad Request
UploadFileAccessViolation	上传文件访问冲突	400 Bad Request
UploadFileNotFound	上传文件不存在	400 Bad Request
UploadFileSaveFailed	上传文件保存至云存储失败	400 Bad Request
UploadFileVerifyFailed	上传文件校验失败	400 Bad Request
ShareSpecialDirError	共享特殊目录	400 Bad Request
SpecialDirShareError	特殊目录分享	400 Bad Request
BatchOperSuccessed	批量操作部分成功	400 Bad Request
BatchOperFileFailed	批量操作失败	400 Bad Request
ShareInfoNotFound	没有找到分享信息	400 Bad Request
InvalidUploadFileStatus	无效的上传文件状态	400 Bad Request
ShareOverLimitedNumber	分享次数超限	400 Bad Request
NotFoundPersonQuestion	没有设置个人问题	400 Bad Request
ShareOverLimitedNumber	分享次数超限	400 Bad Request
InfoSecurityErrorCode	违反信安规则	410 Bad Request
CopyFileOverLimitedSpaceError	转存文件总大小超限	400 Bad Request
CopyFileOverLimitedNumError	转存次数超限	400 Bad Request
InfosecuMD5CheckError	违反信安规则	400 Bad Request
ShareAuditNo/ShareAuditNotPass	分享审核不通过	400 Bad Request
TextAuditErrorCode	敏感词检查不通过	400 Bad Request
UserInvalidOpenToken	无效的天翼账号Token	400 Bad Request
CommonOperNotSupport	操作不支持，建议升级版本	400 Bad Request
PhotoNumOverLimited	照片数量超限	400 Bad Request
FileCopyToSubFolderError	父目录拷贝或移动至自身子目录错误	400 Bad Request
UserDayFlowOverLimited	用户当日流量超过上限	400 Bad Request
PayMoneyNumErrorCode	支付金额有误	400 Bad Request
UserOrderNotExists	用户订单不存在	400 Bad Request
CreateSaleOrderErrorCode	创建用户订单异常	400 Bad Request
ShareDumpFileNumOverLimited	分享转存文件数超限	400 Bad Request
ShareAuditWaiting	分享审核中	400 Bad Request
UploadSingleFileOverLimited	上传单文件大小超限	400 Bad Request
PrivateFileError	异常操作私密空间文文件错误	400 Bad Request
SpeedOrderRecordExist	已经生成订购关系	400 Bad Request
SpeedOrderRecordNotExist	没有找到订购关系	400 Bad Request
SpeedProdAlreadyOrder	该宽带已订购该产品	400 Bad Request
SpeedDialaccountNotFound	找不到宽带账号	400 Bad Request
SpeedNotGdBroadbandUser	非广东宽带拨号用户	400 Bad Request
SpeedUnOrder	智能提速套餐未订购	400 Bad Request
SpeedInfoNotExist	智能提速套餐信息不存在	400 Bad Request
SpeedInfoAlreadyExist	智能提速套餐信息已存在	400 Bad Request
UnSpeedUpError	用户处于未提速状态	400 Bad Request
NotOpenAccount	手机号未创建天翼帐号	400 Bad Request
ObjectIdVerifyFailed	objectId校验失败	400 Bad Request
ErrorAccessCode	分享访问吗错误	400 Bad Request
ShareNotReceiver	好友分享，访问者非接受者	400 Bad Request
CommonInvalidSessionKey	分享相关接口时，好友分享，需要登陆	400 Bad Request
ParasTimeOut	paras参数超时	400 Bad Request
TokenAlreadyExist	该天翼云盘已绑定	400 Bad Request
PrivateFileError	private space file	400 Bad Request
FileStatusInvalid	FMUserFile fileStatus is invalid	400 Bad Request
ShareNotFoundFlatDir	分享平铺目录未找到	400 Bad Request
ShareDumpFileOverload	分享转存文件数目超限	400 Bad Request
ShareNotFound	分享未找到	400 Bad Request
ShareAccessOverload	分享访问次数超限	400 Bad Request
ShareCreateFailed	分享创建失败	400 Bad Request
ShareExpiredError	分享已过期	400 Bad Request
ShareFileNotBelong	文件不属于当前分享文件或目录	400 Bad Request
ShareCreateOverload	用户创建分享次数超限	400 Bad Request
AccountNoAccess	出口ip不在白名单列表中	400 Bad Request
ErrorLogin	登录账号失败，paras只有1分钟有效，且只能请求一次	400 Bad Request
InvalidAccessToken	AccessToken无效	400 Bad Request

3.2REST错误响应

当出现错误时，HTTP响应包含以下Header信息：

HTTP响应码，3xx, 4xx, or 5xx

附录1：

获取AccessToken及获取用户基本信息代码Demo：

import java.util.HashMap;

import java.util.Map;

import java.util.UUID;

public class CloudUtil {

//appKey和appSecret按实际修改，或改成配置中心保存

private static final String APP_KEY = "test";

private static final String APP_SECRET = "test";

private static final String ACCEPT = "application/json;charset=UTF-8";

private static final String DOMAIN = "https://api.cloud.189.cn";

private static final String HOST = "api.cloud.189.cn";

/**

* 获取云盘AccessToken方法

* @param e189AccessToken 天翼账号AccessToken，具体参考账号接口规范

* @return

public static String getAccessToken(String e189AccessToken){

String uri = "/newOpen/oauth2/accessToken.action";

Map<String, Object> headerMap = new HashMap<>();

headerMap.put("Accept", ACCEPT);

Map<String, Object> parameterMap = new HashMap<>();

long now = System.currentTimeMillis();

parameterMap.put("appKey", APP_KEY);

String params="e189AccessToken=test";

String paras=XXTeaUtils.encrypt(params,appSecret);

parameterMap.put("paras", paras);

String signParams=appKey+paras+timeStamp;

String sign;

try {

String privateKey = "MIICdwIBADANBgkqhkiG9w0BAQEFAASCAmEwggJdAgEAAoGBANdd76EASulM9uHHSz5r9HQFrkBK8puiiX3l33jUq9aeUuF70D5qdWJ5WY3DfifY7eHmcSvAS+4IO7Om4IOAqSt7DqqwN/AE4SJGAeBOHH6lv1CRj3VQW2DVqH6F2dfHoUSCA0wvG4fCEGoJLB+N5Fn4QogAcBFiKSEs+w/riDctAgMBAAECgYAK9MZqBF/LOpUcq0zSoh9Pf7J7ptRswnoII5eYyAjt5CQHQIs5gaTzG4VIxvc2A70mTtjXBvNV6qlO3GBzkCoK6lP9Vrq/h4KoZcoZUjo/mjnpqthMdkzouFAIcGzTr+tVOIyqHGm4sTRkmN6yEg3z7XaJOQfgupRfwqtCjpf+gQJBAPCAphSv+ZMRg4Do5JjRbmmldqZFIQv4nvg4yGxkO4XYlgYyqzpCb4iyC3KF+49Rvi492tGIfEZ5Xwr2oJU9O5ECQQDlPqX0IkepsiRXQeak5PPxCvaUEMs8wW5iD/rdAmy/K/QPQBG/Q+TcYDo/yHfJIPf5viKybdIKP6BrzkjNa5vdAkEAgcEG2ZZvkhca2cvMuV4Usc7hiqc1Qx4ptkX8a+5P5tCJcGKZ2t7JCfj1EB6VMCer8YrRqcZ3NhZ5XpLc5Gea4QJBANNm1nswMY3X7ZNZ/mwJhru+NG2Onx1D85sSyXCOD+KrkcGOf881uRNQ2eZ/45bihEsWf8CzbYJt8m34KULl/TECQBI6/w3RhjmPq4rqo+AEDODC8J0jQpl+TlSzpz8KogE2LWyyofkVd3LWi2GZxE8O+xqYstlA4MrKxJQ2ZaGfVxg=";

RSAPrivateKey rsaPrivateKey = RsaUtilWithSHA1.loadPrivateKey(privateKey);

sign= RsaUtilWithSHA1.sign(signParams,rsaPrivateKey);

} catch (Exception e) {

throw new RuntimeException(e);

}

parameterMap.put("timestamp", now);

parameterMap.put("sign", sign);

return OKHttpUtil.doPost(DOMAIN + uri, headerMap, parameterMap);

}

/**

* 获取用户基本信息

* @param accessToken 云盘AccessToken

* @return

public static String getUserInfo(String accessToken){

String uri = "/newOpen/user/getUserInfo.action";

long now = System.currentTimeMillis();

Map<String, Object> headerMap = new HashMap<>();

headerMap.put("X-Request-ID", UUID.randomUUID());

Map<String, Object> parameterMap = new HashMap<>();

parameterMap.put(“appKey”:appKey);

parameterMap.put(“timeStamp”:timeStamp);

parameterMap.put(“accessToken”:accessToken);

parameterMap.put(“paras”:paras);

parameterMap.put(“sign”:sign);

return OKHttpUtil.doPost(DOMAIN + uri, headerMap, parameterMap);

}