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解析
http://www.cnblogs.com/SanMaoSpace/archive/2011/08/16/2141415.html