开发文档
API调用方法详解
开放平台（TOP）的API是基于HTTP协议来调用的，开发者（ISV）可以直接使用TOP提供的官方SDK（支持多种语言，包含了请求的封装，签名加密，响应解释，性能优化等）来调用，也可以根据TOP的协议来封装HTTP请求进行调用，以下主要是针对自行封装HTTP请求进行API调用的原理进行详细解说。
调用流程
根据TOP的协议：填充参数 > 生成签名 > 拼装HTTP请求 > 发起HTTP请求> 得到HTTP响应 > 解释json/xml结果，以下是大体的调用过程示意图：
调用入口
调用API的服务URL地址，AE开放平台目前提供了3个环境给ISV使用：正式测试环境，正式环境，海外环境。
- 正式测试环境：ISV软件上线之前的正式模拟环境，应用创建成功后即可使用。此环境限制API调用为5000次/天，授权用户数量为5个，所能调用的API与应用拥有的权限能力一致。
- 正式环境：ISV软件上线之后使用的环境，此环境的入口与正式测试环境一致，只不过应用上线之后，流量限制会进行打开，具体流量限制与应用所属类目有关，比如服务市场类的应用，限制API调用为100万次/天。
- 海外环境：海外环境也属于正式环境的一种，主要是给海外（欧美国家）ISV使用，对于海外的ISV，使用海外环境会比国内环境的性能高一倍。
| 调用环境 |
服务地址(HTTP) |
服务地址(HTTPS) |
| 正式环境 |
||
| 美国环境 |
公共参数
调用任何一个API都必须传入的参数，目前支持的公共参数有：
| 参数名称 |
参数类型 |
是否必须 |
参数描述 |
| method |
String |
是 |
API接口名称。 |
| app_key |
String |
是 |
TOP分配给应用的AppKey。进入开放平台控制台“应用管理-概览”可查看正式环境AppKey、AppSecret |
| session |
String |
否 |
用户登录授权成功后，TOP颁发给应用的授权信息，详细介绍请点击这里。当此API文档的标签上注明：“需要授权”，则此参数必传；“不需要授权”，则此参数不需要传；“可选授权”，则此参数为可选。 |
| timestamp |
String |
是 |
时间戳，格式为yyyy-MM-dd HH:mm:ss，时区为GMT+8，例如：2016-01-01 12:00:00。淘宝API服务端允许客户端请求最大时间误差为10分钟。 |
| format |
String |
否 |
响应格式。默认为xml格式，可选值：xml，json。 |
| v |
String |
是 |
API协议版本，可选值：2.0。 |
| partner_id |
String |
否 |
合作伙伴身份标识。 |
| target_app_key |
String |
否 |
被调用的目标AppKey，仅当被调用的API为第三方ISV提供时有效。 |
| simplify |
Boolean |
否 |
是否采用精简JSON返回格式，仅当format=json时有效，默认值为：false。 |
| sign_method |
String |
是 |
签名的摘要算法，可选值为：hmac，md5。 |
| sign |
String |
是 |
API输入参数签名结果，签名算法参照下面的介绍。 |
业务参数
API调用除了必须包含公共参数外，如果API本身有业务级的参数也必须传入，每个API的业务级参数请考API文档说明。
签名算法
为了防止API调用过程中被黑客恶意篡改，调用任何一个API都需要携带签名，TOP服务端会根据请求参数，对签名进行验证，签名不合法的请求将会被拒绝。TOP目前支持的签名算法有两种：MD5(sign_method=md5)，HMAC_MD5(sign_method=hmac)，签名大体过程如下：
- 对所有API请求参数（包括公共参数和业务参数，但除去sign参数和byte[]类型的参数），根据参数名称的ASCII码表的顺序排序。如：foo:1, bar:2, foo_bar:3, foobar:4排序后的顺序是bar:2, foo:1, foo_bar:3, foobar:4。
- 将排序好的参数名和参数值拼装在一起，根据上面的示例得到的结果为：bar2foo1foo_bar3foobar4。
- 把拼装好的字符串采用utf-8编码，使用签名算法对编码后的字节流进行摘要。如果使用MD5算法，则需要在拼装的字符串前后加上app的secret后，再进行摘要，如：md5(secret+bar2foo1foo_bar3foobar4+secret)；如果使用HMAC_MD5算法，则需要用app的secret初始化摘要算法后，再进行摘要，如：hmac_md5(bar2foo1foo_bar3foobar4)。
- 将摘要得到的字节流结果使用十六进制表示，如：hex(“helloworld”.getBytes(“utf-8”)) = “68656C6C6F776F726C64”
说明：MD5和HMAC_MD5都是128位长度的摘要算法，用16进制表示，一个十六进制的字符能表示4个位，所以签名后的字符串长度固定为32个十六进制字符。
JAVA签名示例代码
public static String signTopRequest(Map<String, String> params, String secret, String signMethod) throws IOException {
// 第一步：检查参数是否已经排序
String[] keys = params.keySet().toArray(new String[0]);
Arrays.sort(keys);
// 第二步：把所有参数名和参数值串在一起
StringBuilder query = new StringBuilder();
if (Constants.SIGN_METHOD_MD5.equals(signMethod)) {
query.append(secret);
}
for (String key : keys) {
String value = params.get(key);
if (StringUtils.areNotEmpty(key, value)) {
query.append(key).append(value);
}
}
// 第三步：使用MD5/HMAC加密
byte[] bytes;
if (Constants.SIGN_METHOD_HMAC.equals(signMethod)) {
bytes = encryptHMAC(query.toString(), secret);
} else {
query.append(secret);
bytes = encryptMD5(query.toString());
}
// 第四步：把二进制转化为大写的十六进制(正确签名应该为32大写字符串，此方法需要时使用)
//return byte2hex(bytes);
}
public static byte[] encryptHMAC(String data, String secret) throws IOException {
byte[] bytes = null;
try {
SecretKey secretKey = new SecretKeySpec(secret.getBytes(Constants.CHARSET_UTF8), "HmacMD5");
Mac mac = Mac.getInstance(secretKey.getAlgorithm());
mac.init(secretKey);
bytes = mac.doFinal(data.getBytes(Constants.CHARSET_UTF8));
} catch (GeneralSecurityException gse) {
throw new IOException(gse.toString());
}
return bytes;
}
public static byte[] encryptMD5(String data) throws IOException {
return encryptMD5(data.getBytes(Constants.CHARSET_UTF8));
}
public static String byte2hex(byte[] bytes) {
StringBuilder sign = new StringBuilder();
for (int i = 0; i < bytes.length; i++) {
String hex = Integer.toHexString(bytes[i] & 0xFF);
if (hex.length() == 1) {
sign.append("0");
}
sign.append(hex.toUpperCase());
}
return sign.toString();
}
C#签名示例代码
public static string SignTopRequest(IDictionary<string, string> parameters, string secret, string signMethod)
{
// 第一步：把字典按Key的字母顺序排序
IDictionary<string, string> sortedParams = new SortedDictionary<string, string>(parameters, StringComparer.Ordinal);
IEnumerator<KeyValuePair<string, string>> dem = sortedParams.GetEnumerator();
// 第二步：把所有参数名和参数值串在一起
StringBuilder query = new StringBuilder();
if (Constants.SIGN_METHOD_MD5.Equals(signMethod))
{
query.Append(secret);
}
while (dem.MoveNext())
{
string key = dem.Current.Key;
string value = dem.Current.Value;
if (!string.IsNullOrEmpty(key) && !string.IsNullOrEmpty(value))
{
query.Append(key).Append(value);
}
}
// 第三步：使用MD5/HMAC加密
byte[] bytes;
if (Constants.SIGN_METHOD_HMAC.Equals(signMethod))
{
HMACMD5 hmac = new HMACMD5(Encoding.UTF8.GetBytes(secret));
bytes = hmac.ComputeHash(Encoding.UTF8.GetBytes(query.ToString()));
}
else
{
query.Append(secret);
MD5 md5 = MD5.Create();
bytes = md5.ComputeHash(Encoding.UTF8.GetBytes(query.ToString()));
}
// 第四步：把二进制转化为大写的十六进制
StringBuilder result = new StringBuilder();
for (int i = 0; i < bytes.Length; i++)
{
result.Append(bytes[i].ToString("X2"));
}
return result.ToString();
}
其他语言签名示例代码请参见TOP官方SDK源代码。
调用示例
以aliexpress.logistics.redefining.getonlinelogisticsinfo (获取线上发货物流订单信息)调用为例，具体步骤如下：
- 设置参数值
公共参数：
- method = “aliexpress.logistics.redefining.getonlinelogisticsinfo”
- app_key = “12345678”
- session = “test”
- timestamp = “2016-01-01 12:00:00”
- format = “json”
- v = “2.0”
- sign_method = “md5”
业务参数：
- international_logistics_id = “LP00038357949881”
- logistics_status = “INIT”
- 按ASCII顺序排序
- app_key = “12345678”
- format = “json”
- international_logistics_id = “LP00038357949881”
- logistics_status = “INIT”
- method = “aliexpress.logistics.redefining.getonlinelogisticsinfo”
- session = “test”
- sign_method = “md5”
- timestamp = “2016-01-01 12:00:00”
- v = “2.0”
- 拼接参数名与参数值
app_key12345678formatjsoninternational_logistics_idLP00038357949881 logistics_statusINITmethodaliexpress.logistics.redefining.getonlinelogisticsinfosessiontestsign_methodmd5timestamp2016-01-01 12:00:00v2.0
- 生成签名
假设app的secret为helloworld，则签名结果为：hex(md5(helloworld+按顺序拼接好的参数名与参数值+helloworld)) = “66987CB115214E59E6EC978214934FB8” - 组装HTTP请求
将所有参数名和参数值采用utf-8进行URL编码（参数顺序可随意，但必须要包括签名参数），然后通过GET或POST（含byte[]类型参数）发起请求，如：
http://gw.api.taobao.com/router/rest?method=aliexpress.logistics.redefining.getonlinelogisticsinfo&app_key=12345678&session=test×tamp=2016-01-01+12%3A00%3A00&format=json&v=2.0&sign_method=md5& international_logistics_id=LP00038357949881&logistics_status=INIT&sign=66987CB115214E59E6EC978214934FB8
注意事项
- 所有的请求和响应数据编码皆为utf-8格式，URL里的所有参数名和参数值请做URL编码。如果请求的Content-Type是application/x-www-form-urlencoded，则HTTP Body体里的所有参数值也做URL编码；如果是multipart/form-data格式，每个表单字段的参数值无需编码,但每个表单字段的charset部分需要指定为utf-8。
- 参数名与参数值拼装起来的URL长度小于1024个字符时，可以用GET发起请求；参数类型含byte[]类型或拼装好的请求URL过长时，必须用POST发起请求。所有API都可以用POST发起请求。
- 生成签名（sign）仅对未使用TOP官方SDK进行API调用时需要操作，如使用了TOP官方SDK，该步骤SDK会自动完成。
