營銷GIS系統(tǒng)與用電信息采集系統(tǒng)接口方案智能調(diào)度配送管理平臺接口規(guī)范

（地圖服務(wù)系統(tǒng)分冊）二〇一四年十一月智能調(diào)度平臺接口規(guī)范（地圖服務(wù)系統(tǒng)分冊）目錄1. 概述 31.1. 編寫目的 31.2. 預(yù)期讀者 31.3. 術(shù)語 31.4. 交互示意圖 32. 接口需求 32.1. 場站標(biāo)注信息接口 32.1.1. 需求描述 32.1.2. 數(shù)據(jù)類清單 32.1.3. 接口交互流程圖 42.1.4. 流程圖說明 42.1.5. WebService服務(wù)清單 42.2. 氣源地標(biāo)注信息接口 52.2.1. 需求描述 52.2.2. 數(shù)據(jù)類清單 52.2.3. 接口交互流程圖 52.2.4. 流程圖說明 62.2.5. WebService服務(wù)清單 63. Webservice集成 63.1. 場站標(biāo)注信息接口 63.1.1. 場站標(biāo)注信息接口服務(wù) 63.2. 氣源地標(biāo)注信息接口 73.2.1. 氣源地標(biāo)注信息接口服務(wù) 74. WebService接口規(guī)約 84.1. 技術(shù)架構(gòu) 84.1.1. 技術(shù)架構(gòu)概述 84.1.2. 認(rèn)證機制 84.2. 數(shù)據(jù)規(guī)約 104.2.1. Webservice接口數(shù)據(jù)協(xié)議 104.2.2. XML數(shù)據(jù)格式約定 114.2.3. XML數(shù)據(jù)格式示例 114.3. WebServiceWSDL 124.3.1. 地圖服務(wù)系統(tǒng)WSDL 125. 示例 135.1. 示例:嵌套情況 135.2. 示例:返回0行 13

修訂歷史版本類型成稿日期責(zé)任人備注

概述編寫目的為統(tǒng)一智能調(diào)度管理配送平臺與地圖服務(wù)系統(tǒng)的集成接口，特制定本接口規(guī)范，以指導(dǎo)智能調(diào)度管理配送平臺集成的設(shè)計、開發(fā)、測試及部署實施工作。預(yù)期讀者本接口規(guī)范預(yù)期讀者為智能調(diào)度管理配送平臺和地圖服務(wù)系統(tǒng)接口設(shè)計開發(fā)人員。術(shù)語Webservice集成：通過WebService的方式進(jìn)行數(shù)據(jù)傳遞的接口集成方式。交互示意圖接口需求場站標(biāo)注信息接口需求描述根據(jù)智能調(diào)度平臺業(yè)務(wù)開展的要求，需要從GIS系統(tǒng)中獲取場站位置數(shù)據(jù)，為銷售管理、氣源采購管理、運力采購管理、智能匹配管理、運輸執(zhí)行等業(yè)務(wù)開展提供數(shù)據(jù)支撐。數(shù)據(jù)類清單智能調(diào)度配送管理平臺：數(shù)據(jù)類型數(shù)據(jù)類交互頻度場站位置信息場站位置明細(xì)信息實時接口交互流程圖流程圖說明1、智能調(diào)度管理平臺在業(yè)務(wù)過程中，標(biāo)注場站地圖信息并存儲場站地圖信息。2、智能調(diào)度管理平臺調(diào)用地圖服務(wù)系統(tǒng)Webservice接口，通知地圖服務(wù)系統(tǒng)將，并產(chǎn)生的場站位置信息發(fā)送到地圖服務(wù)系統(tǒng)。3、地圖服務(wù)系統(tǒng)接收到智能調(diào)度平臺發(fā)送過來的場站位置信息和Webservice通知后，存儲相關(guān)信息。4、地圖服務(wù)系統(tǒng)將結(jié)果反饋給智能調(diào)度平臺。WebService服務(wù)清單服務(wù)提供者服務(wù)分類服務(wù)名稱地圖服務(wù)系統(tǒng)??氣源地標(biāo)注信息接口需求描述根據(jù)智能調(diào)度平臺業(yè)務(wù)開展的要求，需要從GIS系統(tǒng)中獲取氣源地位置數(shù)據(jù)，為銷售管理、氣源采購管理、運力采購管理、智能匹配管理、運輸執(zhí)行等業(yè)務(wù)開展提供數(shù)據(jù)支撐。數(shù)據(jù)類清單智能調(diào)度配送管理平臺：數(shù)據(jù)類型數(shù)據(jù)類交互頻度氣源地位置信息氣源地位置明細(xì)信息實時接口交互流程圖流程圖說明1、智能調(diào)度管理平臺在業(yè)務(wù)過程中，標(biāo)注氣源地地圖信息并存儲氣源地地圖信息。2、智能調(diào)度管理平臺調(diào)用地圖服務(wù)系統(tǒng)Webservice接口，通知地圖服務(wù)系統(tǒng)，并將產(chǎn)生的氣源地位置信息發(fā)送到地圖服務(wù)系統(tǒng)。3、地圖服務(wù)系統(tǒng)接收到智能調(diào)度平臺發(fā)送過來的氣源地位置信息和Webservice通知后，存儲相關(guān)信息。4、地圖服務(wù)系統(tǒng)將結(jié)果反饋給智能調(diào)度平臺。WebService服務(wù)清單服務(wù)提供者服務(wù)分類服務(wù)名稱地圖服務(wù)系統(tǒng)??Webservice集成場站標(biāo)注信息接口場站標(biāo)注信息接口服務(wù)接口說明接口說明根據(jù)智能調(diào)度平臺業(yè)務(wù)開展的要求，需要從GIS系統(tǒng)中獲取場站位置數(shù)據(jù)，為銷售管理、氣源采購管理、運力采購管理、智能匹配管理、運輸執(zhí)行等業(yè)務(wù)開展提供數(shù)據(jù)支撐。接口方式Webservice方法名稱?服務(wù)端地圖服務(wù)系統(tǒng)調(diào)用端智能調(diào)度管理配送平臺數(shù)據(jù)頻度實時輸入?yún)?shù)中文名輸入?yún)?shù)英文名參數(shù)格式非空含義?????返回值中文名稱返回值英文名稱返回值格式非空含義成功/失敗標(biāo)志RLT_FLAGSTRING(8)1成功0失敗失敗原因FAIL_MEMOSTRING(256)數(shù)據(jù)交互說明氣源地標(biāo)注信息接口氣源地標(biāo)注信息接口服務(wù)接口說明接口說明根據(jù)智能調(diào)度平臺業(yè)務(wù)開展的要求，需要從GIS系統(tǒng)中獲取氣源地位置數(shù)據(jù)，為銷售管理、氣源采購管理、運力采購管理、智能匹配管理、運輸執(zhí)行等業(yè)務(wù)開展提供數(shù)據(jù)支撐。接口方式Webservice方法名稱?服務(wù)端地圖服務(wù)系統(tǒng)調(diào)用端智能調(diào)度管理配送平臺數(shù)據(jù)頻度實時輸入?yún)?shù)中文名輸入?yún)?shù)英文名參數(shù)格式非空含義?????返回值中文名稱返回值英文名稱返回值格式非空含義成功/失敗標(biāo)志RLT_FLAGSTRING(8)1成功0失敗失敗原因FAIL_MEMOSTRING(256)數(shù)據(jù)交互說明WebService接口規(guī)約技術(shù)架構(gòu)技術(shù)架構(gòu)概述智能調(diào)度平臺WebService接口采用Xfire技術(shù)實現(xiàn)。客戶端和服務(wù)器用SOAP協(xié)議通過HTTP來交互，客戶端根據(jù)WSDL描述文檔生成SOAP請求消息發(fā)送到服務(wù)端，服務(wù)端解析收到的SOAP請求，調(diào)用Webservice，然后再生成相應(yīng)的SOAP應(yīng)答送回到客戶端。認(rèn)證機制智能調(diào)度平臺的所有WebService服務(wù)均需要認(rèn)證通過（部分需要授權(quán)）才能夠被調(diào)用。智能調(diào)度平臺WebService服務(wù)接收到請求后首先從消息上下文中獲取用戶名和密碼，進(jìn)行認(rèn)證，認(rèn)證通過后再調(diào)用具體服務(wù)。作為客戶端，應(yīng)用程序代碼(使用Xfire的客戶端編程模型來編寫的)需要將用戶名和密碼設(shè)置到MessageContext中進(jìn)行調(diào)用。根據(jù)客戶端程序語言及調(diào)用方式不同，設(shè)置的方法也不同，下面列舉出客戶端程序語言為java的兩種設(shè)置方式：客戶端調(diào)用平臺使用xfire技術(shù)發(fā)布webservice服務(wù)，建議客戶端也使用XFire來訪問外部服務(wù)，以下客戶端調(diào)用示例代碼都是基于xfire技術(shù)來編寫的。一、調(diào)用方式客戶端可以通過如下兩種方式調(diào)用外部服務(wù)：根據(jù)WSDL創(chuàng)建客戶端調(diào)用如果服務(wù)端沒有提供接口，可以使用這種簡單的方式來調(diào)用，如下為客戶端調(diào)用示例代碼：publicstaticvoidmain(String[]args){ Stringwsdl="4:6001/athena_server/pf_webservice/com.ls.pf.base.impl.auth.extramodel/userService/service?wsdl"; Clientclient=newClient(newURL(wsdl));//invoke第一個參數(shù)為服務(wù)方法名，第二個參數(shù)為服務(wù)參數(shù) Object[]results=client.invoke("isAdmin",newString[]{"SYSADMIN"}); System.out.println(results[0].toString()); results=client.invoke("getUserBySysUserName",newString[]{"SYSADMIN"}); System.out.println(results[0].toString());}通過服務(wù)端提供的接口調(diào)用如果服務(wù)端有提供接口，或者服務(wù)參數(shù)和返回值為復(fù)雜類型時，則建議使用這種方式，客戶端調(diào)用代碼如下：publicstaticvoidmain(String[]args){ Stringwsdl=":7080/amber_server/pf_webservice/com.ls.pf.base.impl.auth.extramodel/userService/service"; ServicesrvcModel=newObjectServiceFactory().create(IUserService.class); XFireProxyFactoryfactory=newXFireProxyFactory(XFireFactory .newInstance().getXFire()); try{ IUserServiceuserService=(IUserService)factory.create(srvcModel,wsdl); XFireProxyproxy=(XFireProxy)Proxy.getInvocationHandler(userService);Clientclient=proxy.getClient(); Booleanresut= userService.isAdmin("SYSADMIN"); }catch(MalformedURLExceptione){ e.printStackTrace(); }}二、添加驗證信息頭當(dāng)訪問的webservice服務(wù)需要進(jìn)行認(rèn)證時，客戶端調(diào)用代碼需要傳入認(rèn)證信息頭，如下分別為服務(wù)端是AuthenticationHandler認(rèn)證和ws-security認(rèn)證時驗證頭添加方式服務(wù)端為AuthenticationHandler認(rèn)證當(dāng)服務(wù)端配置了AuthenticationHandler認(rèn)證時，客戶端通過如下示例代碼添加驗證頭：Clientclient;ClientAuthenticationHandlerhandler= newClientAuthenticationHandler("用戶名","密碼");client.addOutHandler(handler);client.addInHandler(handler)服務(wù)端為ws-security認(rèn)證當(dāng)服務(wù)端配置成ws-security認(rèn)證時，客戶端通過如下示例代碼添加驗證頭。注：認(rèn)證用戶名在pf_user表中的密碼必須為n9zf4TIQEzubAi0PrSL8qHuEgMaXMazk6uh53w5Iclient.addOutHandler(newDOMOutHandler());Propertiesproperties=newProperties();configureOutProperties(properties);client.addOutHandler(newWSS4JOutHandler(properties));privatestaticvoidconfigureOutProperties(Propertiesproperties){ //Actiontoperform:usertokenproperties.setProperty(WSHandlerConstants.ACTION,WSHandlerConstants.USERNAME_TOKEN);//Setpasswordtypetohashedproperties.setProperty(WSHandlerConstants.PASSWORD_TYPE,WSConstants.PW_DIGEST);//Usernameinkeystoreproperties.setProperty(WSHandlerConstants.USER,"SYSADMIN");//Useddoretrivepasswordforgivenusernameproperties.setProperty(WSHandlerConstants.PW_CALLBACK_CLASS,PasswordHandler.class.getName()); }其他的調(diào)用方式及其他語言設(shè)置方式請查閱Xfire相關(guān)文檔。數(shù)據(jù)規(guī)約Webservice接口數(shù)據(jù)協(xié)議采用WebServiceSOAP協(xié)議?？蛻舳撕头?wù)端采用XML格式的字符串來交互業(yè)務(wù)數(shù)據(jù)，客戶端將業(yè)務(wù)數(shù)據(jù)組織成XML格式的字符串作為入?yún)⒄{(diào)用服務(wù)端接口，服務(wù)端解析XML格式的字符串得到業(yè)務(wù)數(shù)據(jù)處理業(yè)務(wù)并把結(jié)果組織成XML格式的字符串返回給客戶端。XML數(shù)據(jù)格式約定業(yè)務(wù)數(shù)據(jù)組織成XML格式的字符串來交互，該XML格式的字符串遵循以下規(guī)則：XML編碼格式為“UTF-8”以<DBSET></DBSET>來標(biāo)記數(shù)據(jù)集的開始和結(jié)束；以<R></R>標(biāo)記一行記錄；以<CN=“字段名”>字段值</C>標(biāo)記字段名稱及值；以<DBSETRESULT=”此處為返回標(biāo)識值”></DBSET>標(biāo)記返回標(biāo)識；字段為日期的遵循以下約定：年月日格式統(tǒng)一為“YYYY-MM-DD”，如“2006-06-22年月格式為“YYYYMM”，如“200606”。XML數(shù)據(jù)格式示例示例：只有數(shù)據(jù)集<?xmlversion="1.0"encoding="UTF-8"?><DBSET><R><CN="dw">0100</C><CN="dwmc">省電力公司</C></R></DBSET>示例：只有返回標(biāo)識<?xmlversion="1.0"encoding="UTF-8"?><DBSETRESULT="0"/>示例：既有返回標(biāo)識，又有數(shù)據(jù)集<?xmlversion="1.0"encoding="UTF-8"?><DBSETRESULT="2"><R><CN="dw">0100</COL><CN="dwmc">省電力公司</COL></R><R><CN="dw">0200</COL><CN="dwmc">地市電力公司</COL></R></D