当前位置： 首页 > news >正文

zzz

news 来源：原创 2024/5/19 8:42:53

开放平台（TOP）的API是基于HTTP协议来调用的，开发者（ISV）可以直接使用TOP提供的官方SDK（支持多种语言，包含了请求的封装，签名加密，响应解释，性能优化等）来调用，也可以根据TOP的协议来封装HTTP请求进行调用，以下主要是针对自行封装HTTP请求进行API调用的原理进行详细解说。

调用流程

根据TOP的协议：填充参数 > 生成签名 > 拼装HTTP请求 > 发起HTTP请求> 得到HTTP响应 > 解释json/xml结果，以下是大体的调用过程示意图：

image

调用入口

调用API的服务URL地址，开放平台目前提供了4个环境给ISV使用：沙箱测试环境，正式测试环境，正式环境，海外环境。

  • 沙箱测试环境： ISV软件的测试环境，应用创建后即可使用。此环境提供简化版的淘宝网，支持大部分场景的API调用，沙箱环境的权限和流量均无限制，可放开使用。
  • 正式测试环境： ISV软件上线之前的正式模拟环境，应用创建成功后即可使用。此环境主要是针对部分无法在沙箱完成测试的场景使用，限制API调用为5000次/天，授权用户数量为5个，所能调用的API与应用拥有的权限能力一致。
  • 正式环境： ISV软件上线之后使用的环境，此环境的入口与正式测试环境一致，只不过应用上线之后，流量限制会进行打开，具体流量限制与应用所属类目有关，比如服务市场类的应用，限制API调用为100万次/天。
  • 海外环境： 海外环境也属于正式环境的一种，主要是给海外（欧美国家）ISV使用，对于海外的ISV，使用海外环境会比国内环境的性能高一倍。

调用环境服务地址(HTTP)服务地址(HTTPS)
沙箱环境 http://gw.api.tbsandbox.com/router/rest https://gw.api.tbsandbox.com/router/rest
正式环境 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。这里要注意正式环境和沙箱环境的AppKey是不同的（包括AppSecret），使用时要注意区分；进入开放平台控制台“应用管理-概览” 和 “应用管理-沙箱环境管理”可分别查看正式环境及沙箱环境的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签名示例代码

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
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());
     }
 
     // 第四步：把二进制转化为大写的十六进制
     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#签名示例代码

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
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. 设置参数值

公共参数：

  • method = “taobao.item.seller.get”
  • app_key = “12345678”
  • session = “test”
  • timestamp = “2016-01-01 12:00:00”
  • format = “json”
  • v = “2.0”
  • sign_method = “md5”

业务参数：

  • fields = “num_iid,title,nick,price,num”
  • num_iid = 11223344

2. 按ASCII顺序排序

  • app_key = “12345678”
  • fields = “num_iid,title,nick,price,num”
  • format = “json”
  • method = “taobao.item.seller.get”
  • num_iid = 11223344
  • session = “test”
  • sign_method = “md5”
  • timestamp = “2016-01-01 12:00:00”
  • v = “2.0”

3. 拼接参数名与参数值

1
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[]类型参数）发起请求，如：

1
http: //gw.api.taobao.com/router/rest?method=taobao.item.seller.get&app_key=12345678&session=test&timestamp=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

注意事项

  • 所有的请求和响应数据编码皆为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发起请求。
  • 如需需要在沙箱环境测试，请在应用控制台的沙箱管理页面获取沙箱环境对应的app_key（一般为正式环境的app_key前面加上“10”）和app_secret，对应的session值也用沙箱帐号登录授权获得，沙箱环境授权和正式环境授权类似，详细可参考用户授权介绍。
  • 生成签名（sign）仅对未使用TOP官方SDK进行API调用时需要操作，如使用了TOP官方SDK，该步骤SDK会自动完成。

FAQ

接口调用报签名错误“ Invalid signature”

相关文章：

  • JS中获取session中传过来的值对象
  • python笔记正则表达式
  • CentOS6下yum搭建LNMP环境
  • testng入门教程9 TestNG依赖测试
  • Mysql安装出现=========== install/remove of the Service Denied
  • 扫码登陆 之我见
  • mongo索引构建
  • 自己用的空气指数实时图的爬虫
  • iOS开发 - 通过NSDate获取年、月、日、星期
  • smarty模板原理
  • python 数组反序的方法
  • 《企业云桌面实施》-小技巧-01-规划注意事项
  • J2SE Base-1
  • mysql零距离接触-存储过程
  • 加速 gradle 编译之屏蔽部分 Task | 掘金技术征文
  • 【159天】尚学堂高琪Java300集视频精华笔记（128）
  • Android Studio：GIT提交项目到远程仓库
  • Apache Pulsar 2.1 重磅发布
  • axios请求、和返回数据拦截，统一请求报错提示_012
  • golang 发送GET和POST示例
  • IOS评论框不贴底（ios12新bug）
  • java架构面试锦集：开源框架+并发+数据结构+大企必备面试题
  • java正则表式的使用
  • miaov-React 最佳入门
  • MySQL Access denied for user 'root'@'localhost' 解决方法
  • python_bomb----数据类型总结
  • python学习笔记－类对象的信息
  • React-redux的原理以及使用
  • Windows Containers 大冒险: 容器网络
  • 构建二叉树进行数值数组的去重及优化
  • 蓝海存储开关机注意事项总结
  • 前言-如何学习区块链
  • 使用 QuickBI 搭建酷炫可视化分析
  • 使用阿里云发布分布式网站，开发时候应该注意什么？
  • 怎么把视频里的音乐提取出来
  • raise 与 raise ... from 的区别
  • （10）STL算法之搜索（二） 二分查找
  • （20050108）又读《平凡的世界》
  • (cljs/run-at (JSVM. :browser) 搭建刚好可用的开发环境!)
  • (javascript)再说document.body.scrollTop的使用问题
  • (附源码)apringboot计算机专业大学生就业指南 毕业设计061355
  • （介绍与使用）物联网NodeMCUESP8266（ESP-12F）连接新版onenet mqtt协议实现上传数据（温湿度）和下发指令（控制LED灯）
  • （学习日记）2024.03.25：UCOSIII第二十二节：系统启动流程详解
  • (原創) 物件導向與老子思想 (OO)
  • （转）项目管理杂谈-我所期望的新人
  • ***利用Ms05002溢出找“肉鸡
  • .a文件和.so文件
  • .NET Framework 3.5中序列化成JSON数据及JSON数据的反序列化，以及jQuery的调用JSON
  • .netcore 获取appsettings
  • /usr/local/nginx/logs/nginx.pid failed (2: No such file or directory)
  • [C++] 如何使用Visual Studio 2022 + QT6创建桌面应用
  • [C++]类和对象【下】
  • [CareerCup] 12.3 Test Move Method in a Chess Game 测试象棋游戏中的移动方法
  • [Linux]——彻底学通权限
  • [NSSCTF]-Web:[SWPUCTF 2021 新生赛]easyrce解析