一、概述
淘宝开放平台SDK提供了API的请求封装、摘要签名、响应解释、消息监听等功能，使用SDK可以轻松完成API的调用、API结果的获取、消息的实时监听。
二、环境依赖
1）JAVA SDK 支持TopAPI、奇门API、消息API，需要依赖 Java SE/EE 1.5 ～ 1.8；2）PHP SDK 支持TopAPI、奇门API，需要依赖 PHP 5及以上；3）Python SDK 支持TopAPI、奇门API，需要依赖 Python 2.X版本；4）.NET SDK 支持TopAPI、奇门API、消息API，需要依赖 .NET Framework 2.0及以上 （不支持Windows Phone平台）；5）.NET Core 支持TopAPI、奇门API、消息API，需要依赖 .NET Core 2.0及以上；6）NodeJS SDK 支持TopAPI、奇门API，需要依赖js 0.8及以上；7）C语言 SDK 支持TopAPI、奇门API，无版本限制。
新版SDK 当前仅包含TopAPI1）JAVA8 SDK 支持 Java 8、Java 112）.NET6 SDK 支持 .NET 6 及以上3）PHP7 SDK 支持 PHP 7 及以上4）Python3 SDK 支持Python3.6及以上5）Go SDK 支持 Go 1.16及以上
三、如何下载
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请求地址
正式环境
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
2. 消息服务地址：
环境
服务地址
SSL服务地址
正式环境
ws://mc.api.taobao.com/
无
五、使用示例
1. 获取单笔交易详情
JAVA 示例：TaobaoClient client = new DefaultTaobaoClient(url, appkey, secret);
//找到对应类，比如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 = new TopClient;
$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 示例：# -*- coding: utf-8 -*-
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++ 示例：pTopRequest pRequest = alloc_top_request();
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 示例：TopClient = require('./topClient').TopClient;
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 示例：TmcClient client = new TmcClient("app_key", "app_secret", "default");
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、JAVA8、.NET6、PHP7、Python3、Go。当然您可以通过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实现方授权（奇门）。
4）请确认下载的SDK版本，不同版本SDK包含的API有区别，详情请参考本文档开头“环境依赖”部分。
6.Q：Python版本的SDK在Python 3.6版本无法运行？
A：目前Python SDK只支持2.X版本。详情请参考本文档开头“环境依赖”部分。