注意:以下文档只适用于TOP接口,请谨慎使用!

文档中心 > 基础技术

TOP-SDK使用说明

更新时间:2020/06/30 访问次数:4098796

概述

淘宝开放平台SDK提供了API的请求封装、摘要签名、响应解释、消息监听等功能,使用SDK可以轻松完成API的调用、API结果的获取、消息的实时监听。

环境依赖

  • JAVA SDK 需要依赖 Java SE/EE 1.5及以上;
  • PHP SDK 需要依赖 PHP 5及以上;
  • Python SDK 需要依赖 Python 2.X版本(当前不支持0及以上版本);
  • .NET SDK 需要依赖 .NET Framework 2.0及以上 (不支持Windows Phone平台);
  • .NET Core 需要依赖 .NET Core 2.0及以上;
  • NodeJS SDK 需要依赖js 0.8及以上;
  • C语言 SDK 无版本限制。

如何下载

应用要先拥有API的访问权限,才能调用此API。所有SDK的下载与应用拥有的权限组相关联,不同的应用下载到的SDK各不相同。

第一步:申请成为淘宝开放平台开发者,并创建一个应用(详细方法请参考新手指南,如果此步已完成,可跳过)。
第二步:进入
淘宝开放平台控制台,点击“应用管理”,进入您的应用管理页面,并选择SDK下载页面。

第三步:选择需要的SDK版本进行下载。

以JAVA版本下载为例。点击“JAVA版本”,可以直接“点击下载”平台默认的JAVA SDK版本;如果您需要下载最新版本的SDK,可以点击“生成“,在跳出的弹框中点击”确定“,系统会生成最新版本的SDK,请耐心等待更新完成,再刷新获取。如下图所示。

注意:生成的SDK不会提示更新完成,一般3-5分钟会生成最新版,需要您手动刷新页面查看。

更新完成后再次点击“JAVA版本”,就能看到最新的SDK,并点击下载。如果等待超过1小时刷新后还没有更新,可以在“淘宝开放平台-->工单支持-->支持中心”提交工单咨询,工单说明清楚您的appkey,并附上SDK生成页面截图。

服务地址

注:服务地址主要用于请求API时填写的URL地址。

 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

消息服务地址:

环境

服务地址

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(url,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);

})

注:更多SDK使用示例详情,请参考《获取单笔交易的详细信息》。

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使用详情,请参考《消息服务使用介绍》。

3、批量调用API

JAVA 示例:
BatchTaobaoClient client = new BatchTaobaoClient("http://gw.api.taobao.com/router/batch", "appkey", "appsecret");

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);

 

注意事项:

  • TaobaoClient或ITopClient的实现类都是线程安全的,所以没有必要每次API请求都新建一个TaobaoClient或ITopClient实现类;
  • 创建TaobaoClient或ITopClient实现类的实例时,指定format=json,相比xml格式,可以减少数据传输量,提升API请求效率;
  • 更多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的时候,示例代码中的port如何获取?

     A:Python示例代码中port为固定值:80,入参时先将port值修改为80,再调用API。 示例:req=top.api.AppstoreSubscribeGetRequest(url,"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版本。详情请参考本文档开头“环境依赖”部分。

 

FAQ

"code":54 Invalid track_id什么错误

iossdk里的demo用户登录后授权后没有跳转

返回
顶部