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解析