Taobao open platform development documents /平台技术-API批量调用简介

平台技术-API批量调用简介

1、为什么要批量调用

可以提高应用性能，更快的响应
比如做一个页面需要调用7个不同的HSF服务拉取数据，然后渲染页面。这种情况下, 如想加快页面响应，可能会考虑并发发起7次HSF调用等到数据都返回来再进行页面渲染。但是这样的编程模型对于调用者来说响应时间会比较长且调用繁琐，如果TOP把7次的HSF调用通过内部串行方式由TOP直接来完成，1次调用返回多个数据结果，那则可以大大提高每次请求响应时间。那对于某些复杂的API调用（单次调用RT可能会达到100MS的业务），那么就有很好的优化效果

使用更少的流量
单次API调用会传重复的系统或者业务入参，比如：sign、method、时间戳、fileds等参数,在很多情况下这些重复参数占用了请求体里面的大部分空间。API批量调用可以将这些参数在协议层面上进行合并，实现参数的复用。对于移动端调用、服务端高并发调用中优化网络使用是很有帮助的。

2、批量调用API特性

支持目前所有安全和业务特性
支持除文件上传外的所有API自由组合调用
支持多session混合调用
调用结果互不干扰
API响应顺序和请求顺序完全一致，无需排序或按编号查询结果
极速体验，M次交易API+N次商品API调用，RT约为1次交易API调用（假设交易API RT> 商品API）
Servlet、HSF、HTTP混合全异步化调用模式，平稳支撑低RT + 高RT混合场景，提高服务端吞吐能力
公共参数和方法名称可进行合并，精简请求报文
简单的调用协议，不用SDK也能快速实现批量API调用

3、批量调用技术简介

3.1 协议内容

请求URL：

http://gw.api.taobao.com/router/batch

POST：

          http://gw.api.taobao.com/router/batch?sign=5336DB2C525E1A3AD1013BC82C4437B2×tamp=2016-01-05+10%3A15%3A15&v=2.0&app_key=4272&sign_method=hmac&format=json &session=6102b110f51625dcd2d1921ba80c6d2b43a2a5a37e7c7c73627811065
         

Content-Type :

text/plain;charset=UTF-8

PAYLOAD：

Payload以from的形式去承载每个API，默认以\r\n-S-\r\n进行分割；参数值需要进行URL Encode
自定义分隔符方式：httpHeader.put(“top-api-separator”,”????”)
第一行#PUBLIC#开始，可提取公共参数和API名称，为可选。如不需要提取公共参数，同时去掉#PUBLIC#行和第一个分隔符
参数优先级：API行参数 ===覆盖===> #PUBLIC#参数 ===覆盖===> URL参数
签名方式，类似于rest签名：hmac（其他类似） byte2hex (hmac(key1value1key2value2...payloadsecret))
占位符：假设你把一个API的所有参数都抽象到了#PUBLIC#区域，请放入一个占位符N，标示我其实是一个API；如上所示

3.2协议内容-响应

Response：情况1

          {"error_response":{"code":25,"msg":"Invalid signature","request_id":"16t6sm38r9709"}}
         

Response：情况2

          {"time_get_response":{"time":"2016-01-05 10:53:02","request_id":"16t6sm2gxmm5q"}}
          
-S-
          
{"time_get_response":{"time":"2016-01-05 10:53:02","request_id":"16t6sm2gxmm5q"}}
          
-S-
          
{"trade_fullinfo_get_response":{"trade":{"orders":{"order":[{"adjust_fee":"0.00","buyer_rate":false,"cid":50069506,"consign_time":"2015-12-03 14:01:07","discount_fee":"0.00","end_time":"2015-12-03 16:18:19","invoice_no":"0000","is_oversold":false,"logistics_company":"电 子凭 证","num":1,"num_iid":2100727710059,"oid":193923500416510,"order_from":"TAOBAO","payment":"11.00","pic_path":"http:\/ \/img04.daily.taobao.net\/bao\/uploaded\/i4 \/TB1EG6SXXXXXXaBXXXXXXXXXXXX_!!0- item_pic.jpg","price":"11.00","refund_status":"NO_REFUND","seller_rate":false,"seller_type":"C","shipping_type":"virtual","snapshot_url":"d:193923500416510_1","status":"TRADE_FINISHED","title":" 测试发布收费课 2015123","total_fee":"11.00"}]},"payment":"11.00","receiver_address":"15988161275","receiver_mobile":"","receiver_name":" 不****","status":"TRADE_FINISHED","tid":193923500416510,"type":"eticket"},"request_id":"16t6sm2gxmm5q"}}
          
-S-
          
{"error_response":{"code":27,"msg":"Invalid session","sub_code":"invalid-sessionkey","request_id":"16t6sm2gxmm5q"}}

Response，情况1：响应报文只有一条结果；比如签名，appkey不存在；这些都是共性，比如我们只进行一次签名，那么一条API签名错误，意味着所以api都会签名错误。
Response，情况2：响应报文和请求报文里面的API个数一致，响应顺序也会和请求顺序保持一致。比如你提交15条请求，可能会出现10条成功，3条流控，2条ＨＳＦ服务提供端异常；但是我们的响应体依然会有１５条请求响应。
自定义分隔符方式：默认分隔符为\r\n-S-\r\n ；自定义方式在提交请求是，使用httpHeader.put(“top-api-separator”,”????”)；请求和响应体分隔符保持一致

4、SDK使用方式

4.1 创建Client

          BatchTaobaoClient client = new BatchTaobaoClient (“http://gw.api.taobao.com router/batch
          
”, “appkey”,“secret");} //注：使用该方式，需要下载最新的sdk，老的sdk暂未支持批量调用功能

4.2 创建BatchRequest

TaobaoBatchRequest batchRequest = new TaobaoBatchRequest();

4.3 添加请求API

          batchRequest.addRequest(timeGetRequest1)
          
.addRequest(timeGetRequest2)
          
.addRequest(timeGetRequest3)
          
.addRequest(timeGetRequest4)
          
.addRequest(fullinfosRequest1)
          
.addRequest(fullinfosRequest2)
          
.addRequest(fullinfosRequest3);

4.4 提交请求

TaobaoBatchResponse response = client.execute(batchRequest);

4.5 遍历结果

          if (response.isSuccess()) {
          
for (int i = 0; i < response.getResponseList().size(); i++)
          
println("body:" + response.getResponseList().get(i).getBody());
          
}

4.6 随机查询结果

          if (response.isSuccess()) {
          
TimeGetResponse resp1 = response.getResponse(timeGetRequest1);
          
if(timeGetResponse1.isSuccess())
          
println(“服务器时间:" + resp1.getTime());
          
TradeFullinfoGetResponse rep2 = response.getResponse(fullinfosRequest3);
          
}

注：使用sdk实现批量api调用功能，需要下载最新的sdk，sdk下载及使用点这里。

5、典型使用场景举例

以调用接口获取订单详情为例，原来要查询某个商家多个订单详情，需要重复发起多次请求；现如果使用批量方式调用，1次请求就可以返回多个结果，可以大大提高API调用效率。以下是常用使用场景sdk调用示例（java）：

5.1、查询单个商家多个订单详情

          BatchTaobaoClient client = new BatchTaobaoClient ( "http://gw.api.taobao.com/router/batch?","test","test");
          
TradeFullinfoGetRequest req1 = new TradeFullinfoGetRequest();
          
req1.setFields( "tid");
          
req1.setTid(6666666666661L); //订单1
          
TradeFullinfoGetRequest req2 = new TradeFullinfoGetRequest();
          
req2.setFields( "tid");
          
req2.setTid(6666666666662L); //订单2
          
TaobaoBatchRequest req = new TaobaoBatchRequest();
          
req.addRequest(req1);
          
req.addRequest(req2);
          
TaobaoBatchResponse rsp = client.execute(req, "test"); //test表示商家的sessionkey

5.2、查询多个商家多个订单详情

          BatchTaobaoClient client = new BatchTaobaoClient ( "http://gw.api.taobao.com/router/batch?","test","test");
          
TradeFullinfoGetRequest req1 = new TradeFullinfoGetRequest();
          
req1.setFields( "tid");
          
req1.setTid(6666666666661L); //商家a的订单1
          
TradeFullinfoGetRequest req2 = new TradeFullinfoGetRequest();
          
req2.setFields( "tid");
          
req2.setTid(6666666666662L); //商家a的订单2
          
TradeFullinfoGetRequest req3 = new TradeFullinfoGetRequest();
          
req3.setFields( "tid");
          
req3.setTid(8888888888881L); //商家b的订单1
          
req3.setBatchApiSession( "testtest"); //商家b的sessionkey
          
TaobaoBatchRequest req = new TaobaoBatchRequest();
          
req.addRequest(req1);
          
req.addRequest(req2);
          
req.addRequest(req3);
          
TaobaoBatchResponse rsp = client.execute(req, "test"); //商家a的sessionkey

5.3、查询多个商家订单和商品详情

          BatchTaobaoClient client = new BatchTaobaoClient ( "http://gw.api.taobao.com/router/batch?","test","test");
          
TradeFullinfoGetRequest req1 = new TradeFullinfoGetRequest();
          
req1.setFields( "tid");
          
req1.setTid(6666666666661L); //商家a的订单1
          
TradeFullinfoGetRequest req2 = new TradeFullinfoGetRequest();
          
req2.setFields( "tid");
          
req2.setTid(6666666666662L); //商家a的订单2
          
ItemSellerGetRequest req3 = new ItemSellerGetRequest();
          
req3.setFields( "num_iid");
          
req3.setNumIid(8888888881L); //商家b的商品1
          
req3.setBatchApiSession( "testtest"); //商家b的sessionkey
          
TaobaoBatchRequest req = new TaobaoBatchRequest();
          
req.addRequest(req1);
          
req.addRequest(req2);
          
req.addRequest(req3);
          
TaobaoBatchResponse rsp = client.execute(req, "test"); //商家a的sessionkey

FAQ

测试环境下与正式环境下的API调用量有限制吗？

← 平台技术-消息服务使用介绍

平台技术-SPI服务接入文档→

Platform introduction

Getting started with development

Business access

E-commerce management

Media advertisement

other

Development documentation

API calling scenarios

Security

common problem