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

文档中心 > 基础技术

TOP-SDK使用说明

更新时间:2024/10/16 访问次数:4766252

一、概述

 

淘宝开放平台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下载页面。

 

image

 

image

 

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

 

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

 

image

 

image

 

image

 

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

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

 

image

 

四、服务地址

 

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

 

1. API服务地址:

 

 

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。当然您可以通过http请求的方式自己拼接请求URL ,请参考《API调用方法详解 》 。

 

image

 

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版本。详情请参考本文档开头“环境依赖”部分。

 

FAQ

"code":54 Invalid track_id什么错误

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

返回
顶部