注意：以下文档只适用于TOP接口，请谨慎使用！
注意：以下文档只适用于TOP接口，请谨慎使用！
淘宝开放平台SDK提供了API的请求封装、摘要签名、响应解释、消息监听等功能，使用SDK可以轻松完成API的调用、API结果的获取、消息的实时监听。
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地址。
API服务地址：
| 环境 |
HTTP请求地址 |
HTTPS请求地址 |
| 正式环境 |
||
| 海外正式环境 |
消息服务地址：
| 环境 |
服务地址 |
SSL服务地址 |
| 正式环境 |
无 |
| 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); }) |
注：更多SDK使用示例详情，请参考《获取单笔交易的详细信息》。
| 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 示例： TaobaoBatchRequest batch = new TaobaoBatchRequest(); TimeGetRequest timeRequest = new TimeGetRequest(); AppipGetRequest ipRequest = new AppipGetRequest(); batch.addRequest(timeRequest).addRequest(ipRequest); TaobaoBatchResponse response = client.execute(batch); System.out.println(response.getBody()); |
| .NET示例： BatchTopClient client = new BatchTopClient("http://gw.api.taobao.com/router/batch", "appkey", "appsecret", "json"); TimeGetRequest timeRequest = new TimeGetRequest(); AppipGetRequest ipRequest = new AppipGetRequest(); TopBatchRequest batch = new TopBatchRequest(); batch.AddRequest(timeRequest).AddRequest(ipRequest); TopBatchResponse rsp = client.Execute(batch); Console.WriteLine(rsp.Body); |
注：更多SDK使用详情，请参考《API批量调用简介》。
（以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 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、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版本。详情请参考本文档开头“环境依赖”部分。
