开放平台(TOP)的API是基于HTTP协议来调用的,开发者(ISV)可以直接使用TOP提供的官方SDK(支持多种语言,包含了请求的封装,签名加密,响应解释,性能优化等)来调用,也可以根据TOP的协议来封装HTTP请求进行调用,以下主要是针对自行封装HTTP请求进行API调用的原理进行详细解说。
根据TOP的协议:填充参数 > 生成签名 > 拼装HTTP请求 > 发起HTTP请求> 得到HTTP响应 > 解释json/xml结果,以下是大体的调用过程示意图:
调用API的服务URL地址,开放平台目前提供了3个环境给ISV使用:正式测试环境,正式环境,海外环境。
调用环境 | 服务地址(HTTP) | 服务地址(HTTPS) |
---|---|---|
正式环境 | http://gw.api.taobao.com/router/rest | https://eco.taobao.com/router/rest |
海外环境 | http://api.taobao.com/router/rest | https://api.taobao.com/router/rest |
调用任何一个API都必须传入的参数,目前支持的公共参数有:
参数名称 | 参数类型 | 是否必须 | 参数描述 |
---|---|---|---|
method | String | 是 | API接口名称。 |
app_key | String | 是 | TOP分配给应用的AppKey。 |
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),签名大体过程如下:
说明: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源代码。
以taobao.item.seller.get调用为例,具体步骤如下:
1. 设置参数值
公共参数:
业务参数:
2. 按ASCII顺序排序
3. 拼接参数名与参数值
app_key12345678fieldsnum_iid,title,nick,price,numformatjsonmethodtaobao.item.seller.getnum_iid11223344sessiontestsign_methodmd5timestamp2016-01-01 12:00:00v2.0
4. 生成签名
假设app的secret为helloworld,则签名结果为:hex(md5(helloworld+按顺序拼接好的参数名与参数值+helloworld)) = “66987CB115214E59E6EC978214934FB8”
5. 组装HTTP请求
将所有参数名和参数值采用utf-8进行URL编码(参数顺序可随意,但必须要包括签名参数),然后通过GET或POST(含byte[]类型参数)发起请求,如:
http://gw.api.taobao.com/router/rest?method=taobao.item.seller.get&app_key=12345678&session=test×tamp=2016-01-01+12%3A00%3A00&format=json&v=2.0&sign_method=md5&fields=num_iid%2Ctitle%2Cnick%2Cprice%2Cnum&num_iid=11223344&sign=66987CB115214E59E6EC978214934FB8