TOP-SDK使用说明.doc

自动化SDK使用指南目录一、新SDK的介绍1二、为什么要使用最新的SDK1三、如何使用最新的SDK11、新SDK的目录结构12、SDK命名规则23、SDK使用代码示例（java版，php版，.net版）24、高级功能4四、下载SDK的地址5一、新SDK的介绍淘宝开放平台最新的SDK是由程序通过API的结构、业务数据等自动化生成的代码包，目前支持主流的三种语言版本（java、php、.net）。是淘宝开放平台为了减少广大开发者使用API的开发成本而提供的一种开发工具包，其中包含了已经开放的API的请求、加密、返回解析等一些必要的功能（目前javasdk支持1.5及以上，.netsdk支持.net2.0及以上，phpsdk支持php5及以上）二、为什么要使用最新的SDK最新的自动化SDK区别之前的版本（前期为人工手写的代码），有着以下多种优势：1、 SDK代码全自动化生成，完全和对外公开的API文档一致2、 自动化生成，避免人工编写产生的Bug3、 在每次API升级发布后，会及时自动升级各语言SDK版本，并向下保持兼容4、 SDK提供了一些基本协议级的封装，提高API访问成功率5、 错误日志自动打印，错误发生时可完全收集现场数据三、如何使用最新的SDK1、新SDK的目录结构JAVA SDK目录结构目录功能1com.taobao.api.domainAPI相关的数据结构包2com.taobao.api.requestAPI的请求参数封装类3com.taobao.api.responseAPI的返回结果封装类4ernalSDK内部调用工具类，不保证以后升级不发生变化，不建议用户直接使用5com.taobao.apiSDK的入口类，如：DefaultTaobaoClient.NET SDK目录结构目录（命名空间）功能1Top.Api.Domain.*API相关的数据结构包2Top.Api.Request.*API的请求参数封装类3Top.Api.Response.*API的返回结果封装类4Top.Api.*Top.Api.Util.*Top.Api.Parser.*SDK内部调用工具类，不保证以后升级不发生变化，不建议用户直接使用5Top.Api.ITopClientSDK的入口类，其实现类为DefaultTopClient2、SDK命名规则a) 数据结构类名与API线上文档中完全一样b) API请求类名：去掉api名字中的”taobao”，把”.”后的首字母大写，再掉所有的”.”号，并加上”Request”，即为最终的类名。比如taobao.user.get对应的请求类的类名为UserGetRequest。c) API返回结果类名：去掉api名字中的”taobao”，把”.”后的首字母大写，再掉所有的”.”号，并加上”Response”，即为最终的类名。比如taobao.user.get对应的响应类的类名为UserGetResponse。d) 默认超时时间为5秒3、SDK使用代码示例（java版，php版，.net版） JAVA版本l 不需要登录（sessionKey）的API调用TaobaoClient client = new DefaultTaobaoClient(url, appkey, secret);UserGetRequest req = new UserGetRequest();req.setFields(nick,sex,buyer_credit,seller_credit ,created,last_visit);req.setNick(hz0799);UserGetResponse response = client.execute(req);if (response.isSuccess() System.out.println(response.getUser().getNick(); else / deal errorl 需要登录（sessionKey）的API调用client.execute(req, sessionKey);l 有文件上传的API调用FileItem img = new FileItem(file);/ FileItem为SDK包里封装好的一个类itemAddRequest.setImage(img); PHP版本n 实例化API Client/实例化TopClient类$c = new TopClient;$c-appkey = 你的appkey;$c-secretKey = 你的secret code;n 不需要登录（sessionKey）的API调用/* * OOP风格的使用方式，下面还有传统的数组方式 */实例化具体API对应的Request类$req = new UserGetRequest;$req-setFields(nick,sex,buyer_credit,seller_credit);$req-setNick(hz0799);/执行API请求并打印结果$resp = $c-execute($req);n 需要登录（sessionKey）的API调用/实例化具体API对应的Request类$req = new UserGetRequest;$req-setFields(nick,sex,buyer_credit,seller_credit, birthday);/这行和上面不同，登录用户可以获取隐私字段$req-setNick(hz0799);/执行API请求并打印结果$resp = $c-execute($req, $sessionKey);/这行和上面不同n 有文件上传的API调用$req = new TaobaoItemImgUploadRequest;$req-setNumIid(12345678);$req-setImage(C:my_pictureitem_1.jpg);/附件上传的机制参见PHP CURL文档，在文件路径前加符号即可$resp = $c-execute($req);print_r($resp);n 传统的数组方式调用（适合已有APP迁移到PHP SDK的客户）/* * 非OOP风格的使用方式, 兼容已有的PHP应用 */$req_array = array(method = taobao.items.search,fields = iid,title,q = ipad,page_size = 3,location.city = 杭州);$resp = $c-exec($req_array);print_r($resp); .NET版本n 不需要登录（sessionKey）的API调用ITopClient client = new DefaultTopClient(url, appkey, appsecret);UserGetRequest req = new UserGetRequest();req.Fields = user_id,nick,created,buyer_credit,type,sex;req.Nick = helloworld;UserGetResponse rsp = client.Execute(req);if (rsp.IsError)Console.WriteLine(rsp.Body);n 需要登录（sessionKey）的API调用ITopClient client = new DefaultTopClient(url, appkey, appsecret);TradeGetRequest req = new TradeGetRequest();req.Fields = “tid,seller_nick,buyer_nick”;req.Tid = 129318293L;TradeGetResponse rsp = client.Execute(req, sessionKey);n 有文件上传的API调用ITopClient client = new DefaultTopClient(url, appkey, appsecret);ItemAddRequest req = new ItemAddRequest();req.Image = new FileItem(“c:/temp.jpg”);ItemAddResponse rsp = client.Execute(req, sessionKey);4、高级功能n SDK支持设置客户端的请求超时时间，设置方法为使用支持传入超时参数的构造函数来构造DefaultTaobaoClient，如:public DefaultTaobaoClient(String serverUrl, String appKe