java公共服务的接口文档如何设计管理

服务端接口文档

集成服务端接口之前，请先确保已在开发者中心将服务器出口IP添加到个像白名单列表。

鉴权接口

功能说明

该接口为鉴权接口，在调用获取新画像接口之前，需先调用该接口进行鉴权，只有鉴权 成功的用户，才可以继续调用其他接口。

URL

HTTP请求方式

POST

请求参数

参数名称

参数类型

备注

sign

String

sha256(appKey+timeStamp+masterSecret)

timestamp

Long

生成sign的时间戳

请求参数JSON示例：

{
"sign": "ec6536dfad5e1554ab12f777da55f5de2f36db32db7002a4784601b5469d1567",
"timestamp": 1528855537000
}

JSON返回示例

成功：

{
"result": true,
"authtoken": "334a8e7abc96f15a99e9a2e796f7966f2737bee12e407ef534720fdbbccef073"
}
失败：
{
"error_info": {
"error_code": 304,
"error_msg": "IP受限"
}

}鉴权生成的 authtoken 是有过期时间的，若 token 已过期，需重新进行鉴权。

画像查询接口

功能说明

查询目标用户的画像标签信息

URL

HTTP请求方式

POST

请求参数

参数名称

参数类型

备注

token

String

鉴权接口返回的authtoken

userIdList

List

giuid列表

请求参数JSON示例：

{
"userIdList": [
"32e1d2b480sd772a5b16929c2bb4264a"，
"41e1d2b48031772a5b16929c2bb4264b"
],
"token": "334a8e7abc96f15a99e9a2e796f7966f2737bee12e407ef534720fdbbccef073"
}
JSON返回示例
{
"userTag": [
{
"error_code": 0,
"userId": "32e1d2b480sd772a5b16929c2bb4264a",
"tags": [
{
"code": "010wyq00",
"weight": 3
},
{
"code": "010wyi00",
"weight": 1
},
{
"code": "010wyq00",
"weight": 3
},
{
"code": "010eq000"
},
{
"code": "010wq000",
"weight": 1
},
{
"code": "010wyr00",
"weight": 2
},
{
"code": "010iri",
"weight": 1
},
{
"code": "c33000000"
}
]
},
{
"error_msg": "用户暂无画像",
"error_code": 105,
"userId": "41e1d2b48031772a5b16929c2bb4264b"
}
]

}userIdList 最大可同时上传 200 个 userIdList。

code：画像标签编码(标签编码对照表详见资料包)

weight：画像标签权重(1：高，2：中，3：低)，没有weight则表示此标签无画像权重。

错误码

错误码

说明

0

成功

102

参数格式错误

105

暂无画像

106

IP 白名单鉴权失败

107

IP 白名单鉴权异常

109

查询用户画像失败

112

用户暂无画像

302

token 已过期

303

获取用户相关信息失败

304

IP 受限

305

一分钟内获取画像频次超限

307

一天内获取画像总量超限

308

APPID 不匹配

309

APPID 和 APPKEY 不匹配

310

画像接口每分钟最大量超限

311

不是老用户，不能调用该接口

400

生成鉴权 token 失败

401

鉴权频次超限

402

鉴权一分钟请求总量超限

403

鉴权异常

404

验证 sign 失败

500

无此接口

501

未传 APPID

502

未知应用

503

其他错误

Demo示例

获取token

public class AuthSignTest {
static String url = " https://openapi-gi.getui.com/v2/{appid}/auth_sign";
public static void main(String[] args) throws Exception{
URL urlObj = new URL(url);
URLConnection con = urlObj.openConnection();
HttpURLConnection httpURLConnection = (HttpURLConnection) con;
// http 头部
httpURLConnection.setRequestMethod("POST");
httpURLConnection.setDoOutput(true);
httpURLConnection.setRequestProperty("Content-Type", "text/html;charset=UTF-8");
Long timestamp = System.currentTimeMillis();
// 在个像开发者中心获取的 app 对应的 key，可自行替换
String appkey = "GH4u6fBaYqABoG7bgwAkn5";
String masterSecret = "iMPZBVYZYPAfyZSnWVsAs";
// sha256 加密，使用 org.apache.commons 包中自带的加密方法，需将加密后数据一 起上传
String sign = DigestUtils.sha256Hex(String.format("%s%d%s", appkey, timestamp, masterSecret));
JSONObject requestDataObject = new JSONObject();
requestDataObject.put("sign", sign);
requestDataObject.put("timestamp", timestamp);
// 建立连接，将数据写入内存
DataOutputStream out = new DataOutputStream(httpURLConnection.getOutputStream());
out.writeBytes(requestDataObject.toString());
out.flush();
out.close();
BufferedReader in = null;
String result = "";
// 将数据发送给服务端，并获取返回结果
in = new BufferedReader(new InputStreamReader(httpURLConnection.getInputStream()));
String line;
while ((line = in.readLine()) != null) {
result += line;
}
System.out.println(result);
}
}

查询用户画像

public class GetUserTagTest {
static String url = " https://openapi-gi.getui.com/v3/{appid}/query_tag";
public static void main(String[] args) throws Exception {
URL urlObj = new URL(url);
URLConnection con = urlObj.openConnection();
HttpURLConnection httpURLConnection = (HttpURLConnection) con;
// http 头部
httpURLConnection.setRequestMethod("POST");
httpURLConnection.setDoOutput(true);
httpURLConnection.setRequestProperty("Content-Type", "text/html;charset=UTF-8");
// 需上传的参数，userIdList和token，token为鉴权成功后返回的字符串
JSONObject requestDataObject = new JSONObject();
List userList = new ArrayList();
userList.add("b154c3fb51c213cbfb25edee3b55d127");
userList.add("124587587853829478436231112");
requestDataObject.put("token", "cb2b16456ba3943f19ed0b54e8902b53db2aa288a2e4d56ae88aff93e0f94eef");
requestDataObject.put("userIdList", userList);
// 建立连接，将数据写入内存缓冲区
DataOutputStream out = new DataOutputStream(httpURLConnection.getOutputStream());
out.writeBytes(requestDataObject.toString());
out.flush();
out.close();
// 发送数据给个像服务端，并获得返回结果
BufferedReader in = null;
String result = "";
in = new BufferedReader(new InputStreamReader(
httpURLConnection.getInputStream()));
String line;
while ((line = in.readLine()) != null) {
result += line;
}
System.out.println(result);
}
}