手册

平台简介

开发入门

新手指南应用权限说明

业务接入

移动应用-互动到店业务 TVOS游戏业务 YUNOS开放业务阿里百川业务

电商管理

第三方IT工具商家后台系统应用服务商后台系统应用千牛开放业务阿里.去哪儿业务 WMS（仓储管理系统）业务接入指南天猫品牌会员

媒体广告

淘宝客

其他

云盾魔方

开发文档

API列表平台技术-API调用协议平台技术-用户授权介绍平台技术-应用环境介绍平台技术-Java SDK使用说明平台技术-.NET SDK使用说明平台技术-API调用示例平台技术-消息服务使用介绍平台技术-API批量调用简介平台技术-SPI服务接入文档平台功能-沙箱环境说明平台功能-支付宝API开发帮助平台功能-API文档其他查看方式平台功能-多店铺管理平台功能-应用安全保障设置平台功能-聚石塔塔外测试方法平台功能-子账号授权流程介绍（新）平台功能-子账号授权改造升级介绍平台功能-子账号授权改造升级影响范围平台功能-Q&A 平台功能-API报表功能介绍平台功能-API监控预警解释常用工具-问题反馈系统 API异常排查方法 API相关工具使用说明消息服务问题自助排查

安全保障

数据加密简介数据加密接入指南账号体系接入方案应用代码开发方案密文字段检索方案历史数据迁移方案 API字段加密文档常见问题数据加密培训视频

首页后端开发 PHP 淘宝开放平台开发文档

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

阅读24616

更新时间2022-04-11

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

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

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&timestamp=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服务接入文档