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