TaoBaoAPI简介2

ATS使用指南

(本篇是对ATS的简单使用指南！)

1.什么是异步任务
<a.>调用atsapi生成异步任务
<b>.返回任务号或者错误信息
<c>.任务执行完成通知
<d>.指定任务号获取任务结果
<e>.返回任务执行状态或结果

请求执行异步任务-->等待较长时间-->获取任务结果
(注：目前最大支持40条数据的传入，大概5分钟内可以完成单个任务

2.异步API的特点：
<1>.执行批量任务；
<2>.任务执行周期较长或返回结果较大；
<3>.错误分级产生：低级错误（参数不匹配、格式有问题等）不生成任务直接报错；
<4>.业务错误(入参格式正确但不存在权限或逻辑问题)在子任务结果中显示；
<5>.任务完成主动通知（有在top留下notifyUrl的isv）；
<6>.任务结果获取按状态过滤(未完成任务只返回状态，已完成任务返回详细结果信息)，支持历史任务结果查询

3.目前提供的ATS相关的API
目前提供三个异步信息的API：实现的功能分别是批量订单详情获取，批量发货和获取异步任务结果对应的API分别是：
<1>.异步批量互殴妻交易订单详情API:
taobao.topats.trades.fullinfo.get
文档地址：http://my.open.taobao.com/apidoc/index.html#path:categoryId:39-apiId:10417
<2>.异步批量物流发货API:
taobao.topats.delivery.send
文档地址:http://my.open.taobao.com/apidoc/index.html#path:categoryId:39-apiId:10416
<3>.获取异步任务结果：
taobao.topats.result.get
文档地址：http://my.open.taobao.com/apidoc/index.html#path:categoryId:39-apiId:10415
<4>.异步获取淘宝卖家绑定的支付宝帐号的财务明细
taobao.topats.accountreport.get
文档地址：http://my.open.taobao.com/apidoc/index.htm#categoryId:10082-apiId:10461

4.如何调用ATS服务执行任务
<1>.开通调用atsapi的权限
<2>.根据文档拼装参数，按照正常api调用方法调用生成任务的api
<3>.获取返回结果：如果错误按照说明更正，如果正确保存下task_id(任务id号)

5.如何获取ats任务完成后的主动通知(目前只有标签是"淘宝商家"可使用)
<1>.notify url如何设置：
<2>.获取任务结果的操作步骤：
<a>.Isv服务器部署一个HttpServlet服务
<b>.在top保留下该服务的url地址
<c>.解析收到的http请求内容

6.示例代码：
public class NotifiyReceiveServlet extends HttpServlet
{
 private static final long serialVersionUID=5411581559914704110L;
 @Override
 protected void doGet(HttpServletRequest req,HttpServletResponse  reap)
 throws ServletExceptoin,IOException{}
 //get方法ats服务暂时不需要，如有其他消息需要使用请根据其他文档进行处理
 @Override
 protected void doPost(HttpServletRequest req,HttpServletResponse resp)throws ServletException,IOException{
 //解析收到的消息内容
 //消息属于哪个appkey
 String appKey;
 //消息发送的时间
 String timestamp;
 //消息的版本号(由发送方确定，用于区隔不同版本的消息的解析问题， ats默认是2.0)
 //String version;
 //消息内容的格式(可以为jsion或xml,ats的消息默认都是jsion格式的)
 String format;
 //消息是有什么API产生的(ats发送的method是任务所属的api的名称)
 String method;
 //消息内容的签名(保证消息内容不被篡改，防攻击用，签名算法同top的 签名算法一致)
 String sign;
 //消息内容的正文(ats消息的内容格式为:("task":("task_id":123456;"created":"2010-10-10 12:00:00")))
 String message;

 if(null!=request.getParameterMap())
 {
  //从请求中取出对应的参数
  appKey=request.getParameter("app_key");
  timestamp=request.getPrameter("timestamp");
  version=request.getParameter("v");
  fomat=request.getParameter("format");
  method=request.getParameter("method");
  sign=request.getParameter("sign");
  message=request.getParameter("message");
  //进行参数校验，确定消息是否合法(isv根据自己逻辑进行填充)
  checkParams(--);
  //根据消息内容中的task_id和created进行业务处理
  getAtsResult(message);
 }
 else{//如果请求中没有采纳数，忽略此消息 }
 //给予top请求处理完成相应，只能返回true,如果不给予正确的处理响应 ，top会将此消息重复发送3遍以保证消息正确到达
 resp.getWriter().printin(true);
}
}

7.如何获取ats任务结果
<1>.使用taobao.topats.result.get传入task_id
<2>.获取Task数据列表
Task 所属类目：增量API 描述：批量异步任务结果

名称  类型 是否隐私 文档是否可见 示例值   描述
task_id:Number 否 是 12345 异步任务id,创建异步任务时,返回id号
status :String 否 是 doing 异步任务处理状态,new(还未开始处理)，                           doing(处理中)，done(处理结束)
subtasks:Subtask[] 否 是   子任务处理结果，如果任务还没有处理完，                           返回的结果列表为空；
                           如果任务处理完毕，返回子任务结果列表
method:String 否 是 taobao.topats.trades.fulinfo.get
                           此任务是由哪个api产生的
如果status的状态是done的时候就可以拿到处理结果，有XML和JSON两种行事进行展现（推荐使用JSON方式）
JSON示例：
{
 "topats_result_get_response":{
  "task":{
      "task_id":12345,"status":"done","subtasks":{
         "item":[{"sub_task_request":"{"tid":123456,"fields":"tid,seller_nick"}",
"sub_task_result":"{"trade":{"tid":123456,"seller_nick":"淘宝卖家""}]},
"method":"taobao.topats.trades.fulinfo.get"
}
}
}
XML示例：
<topats_result_get_response>
 <task>
  <task_id>
  123456
  </task_id>
  <status>
  done
  </status>
  <subtasks list="true">
   <subtask>
    <sub_task_request>
     {"tid":"123456","fields":"tid,seller_nick"}
    </sub_task_request>
    <sub_task_result>
     {"trade":{"tid":123456,"seller_nick":"淘宝卖家"}}
    </sub_task_result>
   </subtask>
  </subtasks>
  <method>
   taobao.topats.trades.fullinfo.get
  </method>
 </task>
</topats_result_get_response>

8.注意事项：
<1>.参数拼装要仔细（一一对应、格式正确、长度合法）
<2>.错误信息分为低级错误（直接报错）和业务错误（任务成功创建，但是里面某些子任务的sub_task_result中填充的是sub_code和sub_msg信息）解析逻辑要严密
<3>.每种类型的任务返回的sub_task_result内容都不同，isv需要根据method和文档说明格式进行匹配解析
<4>.sub_task_request和sub_task_result返回的是每个子任务传入的参数和返回结果，如果子任务出现错误，isv可以查看相关信息进行调整，禁止一个子任务错误整个任务重新执行
<5>.sub_task_request和sub_task_result返回的格式都是json的，因此使用xml格式的isv注意将子任务的结果分开用json解析