基础技术
一、概述
淘宝开放平台SDK提供了API的请求封装、摘要签名、响应解释、消息监听等功能，使用SDK可以轻松完成API的调用、API结果的获取、消息的实时监听。
二、环境依赖
1）JAVA SDK 需要依赖 Java SE/EE 1.5及以上；
2）PHP SDK 需要依赖 PHP 5及以上；
3）Python SDK 需要依赖 Python 2.X版本；
4）.NET SDK 需要依赖 .NET Framework 2.0及以上 （不支持Windows Phone平台）；
5）.NET Core 需要依赖 .NET Core 2.0及以上；
6）NodeJS SDK 需要依赖js 0.8及以上；
7）C语言 SDK 无版本限制。
三、如何下载
SDK生成逻辑是根据当前应用appkey拥有的API权限组来生成SDK的，所以不同的appkey生成的SDK各不相同。而且应用需要拥有API的权限，才能调用对应API接口。
第一步：申请成为淘宝开放平台开发者，并创建一个应用（详细方法请参考新手指南，如果此步已完成，可跳过）。
第二步：进入淘宝开放平台控制台，选择【开发 -> 应用管理 -> 我的应用】页面，点击对应应用的【应用管理】按钮，选择SDK下载页面。
第三步：选择需要的SDK版本进行下载。
以JAVA版本下载为例。点击“JAVA版本”，可以直接“点击下载”平台默认的JAVA SDK版本；如果您需要下载最新版本的SDK，可以点击“生成“，在跳出的弹框中点击”确定“，系统会生成最新版本的SDK，请耐心等待更新完成，再刷新获取。如下图所示。
注意：生成的SDK不会提示更新完成，一般3-5分钟会生成最新版，需要您手动刷新页面查看。
更新完成后再次点击“JAVA版本”，就能看到最新的SDK，并点击下载。如果等待超过1小时刷新后还没有更新，可以在【淘宝开放控制台 -> 支持 ->服务中心 -> 提交工单】提交工单咨询，工单说明清楚您的appkey，并附上SDK生成页面截图。
四、服务地址
注：服务地址主要用于请求API时填写的URL地址。
1. API服务地址：
| 环境 |
HTTP请求地址 |
HTTPS请求地址 |
| 正式环境 |
||
| 海外正式环境 |
2. 消息服务地址：
| 环境 |
服务地址 |
SSL服务地址 |
| 正式环境 |
ws://mc.api.taobao.com/ |
无 |
五、使用示例
1. 获取单笔交易详情
| JAVA 示例： //找到对应类，比如taobao.trade.fullinfo.get接口对应的请求类为TradeFullinfoGetRequest TradeFullinfoGetRequest req = new TradeFullinfoGetRequest(); //设置业务参数 req.setFields("tid,type,status,payment,orders,promotion_details"); req.setTid(123456789L); TradeFullinfoGetResponse rsp = client.execute(req, sessionKey); System.out.println(rsp.getBody()); |
| PHP 示例： $c->appkey = $appkey; $c->secretKey = $secret; $req = new TradeFullinfoGetRequest; $req->setFields("tid,type,status,payment,orders,promotion_details"); $req->setTid("123456789"); $resp = $c->execute($req, $sessionKey); |
| Python 示例： import top.api req=top.api.TradeFullinfoGetRequest(domain,port) req.set_app_info(top.appinfo(appkey,secret)) req.fields="tid,type,status,payment,orders,promotion_details" req.tid=123456789 try: resp= req.getResponse(sessionkey) print(resp) except Exception,e: print(e) |
| .NET示例： ITopClient client = new DefaultTopClient(url, appkey, secret); TradeFullinfoGetRequest req = new TradeFullinfoGetRequest(); req.Fields = "tid,type,status,payment,orders,promotion_details"; req.Tid = 123456789L; TradeFullinfoGetResponse rsp = client.Execute(req, sessionKey); Console.WriteLine(rsp.Body); |
| C/C++ 示例： pTopResponse pResponse = NULL; pTaobaoClient pClient = alloc_taobao_client(url, appkey, appsecret); set_api_name(pRequest,"taobao.trade.fullinfo.get"); add_param(pRequest,"fields","tid,type,status,payment,orders,promotion_details"); add_param(pRequest,"tid","123456789"); pResponse = top_execute(pClient,pRequest,sessionKey); printf("ret code:%d\n",pResponse->code); if(pResponse->code == 0){ pTopResponseIterator ite = init_response_iterator(pResponse); pResultItem pResultItem = alloc_result_item(); while(parseNext(ite, pResultItem) == 0){ printf("%s:%s\n",pResultItem->key,pResultItem->value); } destroy_response_iterator(ite); destroy_result_item(pResultItem); } destroy_top_request(pRequest); destroy_top_response(pResponse); destroy_taobao_client(pClient); |
| NodeJS 示例： var client = new TopClient({ 'appkey': 'appkey', 'appsecret': 'secret', 'REST_URL': 'http://gw.api.taobao.com/router/rest' }); client.execute('taobao.trade.fullinfo.get', { 'fields':'tid,type,status,payment,orders,promotion_details', 'tid':'123456789' }, function(error, response) { if (!error) console.log(response); else console.log(error); }) |
2. 监听实时消息通知
| JAVA 示例： client.setMessageHandler(new MessageHandler() { public void onMessage(Message message, MessageStatus status) { try { System.out.println(message.getContent()); System.out.println(message.getTopic()); } catch (Exception e) { e.printStackTrace(); status.fail();// 消息处理失败回滚，服务端需要重发 } } }); client.connect("ws://mc.api.taobao.com/"); |
| .NET示例： TmcClient client = new TmcClient("app_key", "app_secret", "default"); client.OnMessage += (s, e) => { try { Console.WriteLine(e.Message.Content); Console.WriteLine(e.Message.Topic); // 默认不抛出异常则认为消息处理成功 } catch (Exception exp) { Console.WriteLine(exp.StackTrace); e.Fail(); // 消息处理失败回滚，服务端需要重发 } }; client.Connect("ws://mc.api.taobao.com/"); |
注：更多SDK使用详情，请参考《消息服务使用介绍》。
六、高级功能
（以JAVA和.NET为例）
| 功能 |
JAVA示例 |
.NET示例 |
| 不解释响应字符串为对象 |
DefaultTaobaoClient.setNeedEnableParser(false) （这时候XxxResponse包含的对象为null） |
DefaultTopClient.SetDisableParser(true) |
| 采用精简化的JSON结构返回，去除多余JSON节点 |
DefaultTaobaoClient.setUseSimplifyJson(true) |
DefaultTopClient.SetUseSimplifyJson(true) |
| 取消API调用日志打点 |
DefaultTaobaoClient.setNeedEnableLogger(false) |
DefaultTopClient.SetDisableTrace(true) |
| 忽略HTTPS证书检查（建议只在测试环境打开） |
DefaultTaobaoClient.setIgnoreSSLCheck(true) |
DefaultTopClient.SetIgnoreSSLCheck(true) |
| 取消响应GZIP压缩功能（GZIP压缩功能可以显著的减少网络传输，强烈建议不要取消） |
DefaultTaobaoClient.setUseGzipEncoding(false) |
DefaultTopClient.SetUseGzipEncoding(false) |
| 设置HTTP连接超时和读超时时间（网络环境差的情况下可以适当增大） |
// HTTP连接默认超时时间为：3秒 // HTTP响应读默认超时时间为：15秒 DefaultTaobaoClient client = new DefaultTaobaoClient("http://gw.api.taobao.com/router/rest", "appkey", "appsecret", connectTimeout, readTimeout |
// HTTP等待请求开始返回的超时时间：默认20秒 DefaultTopClient.SetTimeout(20000L) // HTTP等待读取数据完成的超时时间：默认60秒 DefaultTopClient.SetReadWriteTimeout(60000L) |
| API调用出错自动重试（一般情况下ISP类的错误是可以重试成功的） |
AutoRetryTaobaoClient client = new AutoRetryTaobaoClient("http://gw.api.taobao.com/router/rest", "appkey", "appsecret"); client.setMaxRetryCount(3); client.setRetryWaitTime(100L); TimeGetRequest request = new TimeGetRequest(); TimeGetResponse response = client.execute(request); if (response.isSuccess()) { System.out.println(response.getBody()); } |
AutoRetryTopClient client = new AutoRetryTopClient("http://gw.api.taobao.com/router/rest", "appkey", "appsecret", "json"); client.SetMaxRetryCount(3); client.SetRetryWaitTime(100L); TimeGetRequest request = new TimeGetRequest(); TimeGetResponse response = client.Execute(request); if (!response.IsError) { Console.WriteLine(response.Body); } |
| API调用就近路由（根据API发起调用所在地选择就近的TOP机房进行调用） 注意：请保持 ClusterTaobaoClient为单例 |
ClusterTaobaoClient client = new ClusterTaobaoClient("http://gw.api.taobao.com/router/rest", "appkey", "appsecret"); TimeGetRequest request = new TimeGetRequest(); TimeGetResponse response = client.execute(request); System.out.println(response.getBody()); |
ClusterTopClient client = new ClusterTopClient("http://gw.api.taobao.com/router/rest", "appkey", "appsecret", "json"); TimeGetRequest request = new TimeGetRequest(); TimeGetResponse response = client.Execute(request); Console.WriteLine(response.Body); |
注意事项：
1）TaobaoClient或ITopClient的实现类都是线程安全的，所以没有必要每次API请求都新建一个TaobaoClient或ITopClient实现类；
2）创建TaobaoClient或ITopClient实现类的实例时，指定format=json，相比xml格式，可以减少数据传输量，提升API请求效率；
3）更多API信息，请查看API文档。
七、常见问题
1.Q：TOP目前支持的SDK语言都有哪些？
A：目前封装好的SDK包括：JAVA、PHP、Python、.NET、.NET Core、Metadata、C、 NodeJS。当然您可以通过http请求的方式自己拼接请求URL ，请参考《API调用方法详解 》 。
2.Q：SDK中有些接口的类没有吗？
A： 请在“控制台-->应用管理-->APP证书-->功能场景”查看已获得的API权限组，及可申请的权限组。 点击对应权限组的详情查看对应API列表，如果已获得及可申请的权限组都不包含对应的API，则不支持申请该接口。（具体方法请参考《应用证书权限管理》）
3.Q：开放平台的SDK是否支持Maven库？
A：目前开放平台的SDK没有提供Maven库。
4.Q：使用python SDK的时候，示例代码中domain和port如何获取？
A：Python SDK的domain为http请求地址域名(不包含协议和路径)，例如gw.api.toabao.com、eco.toabao.com；port与http请求地址协议有关，http协议port为80，https协议port为443 示例：req=top.api.AppstoreSubscribeGetRequest("gw.api.toabao.com","80")。
5.Q：SDK找不到对应的类？
A：1）请确定API是否有相关的权限包（TOP）；
2）如果是实现方找不到，请确定API实现方是否已经自测完（奇门）；
3）如果是调用方找不到，请确定appkey是否已被API实现方授权（奇门）。
6.Q：Python版本的SDK在Python 3.6版本无法运行？
A：目前Python SDK只支持2.X版本。详情请参考本文档开头“环境依赖”部分。
