開放式車載雲端服務管理平台 SDK
使用者開發指南說明書
1、技術項目簡介:
開放式車載雲端服務管理平台:
「開放式車載雲端服務平台」(以下簡稱本平台),利用車輛作為感測器
(Sensor),蒐集道路狀況與駕駛人操控車輛的行為。在蒐集車輛資訊後,利用車
載事件探勘引擎,進行資料分析,產生特定路段的特殊行為特徵模式。將特定路
段的駕駛人特殊行為模式儲存至資料庫,可提供危險駕駛行為預測、導航往返時
間預測、前方特殊路況警示等功能。本平台所提供之服務可將前方路況資訊提供
給駕駛人,除了可避開特殊路況事件達到節能省油外,亦可提升駕駛人行車安全
與行車舒適程度。
2、應用範圍說明
本平台提供 SDK(Software Development Kit),供開發者利用本平台所提供之
路況資訊,提供加值服務。SDK包含:路況事件存取 API、範例程式、與教學
說明文件。本教學說明文件將針對路況事件存取 API與範例程式的使用方式進
行說明。使開發者可利用路況事件存取 API,開發加值應用服務。
3、安裝指南說明
3.1. 所需之系統軟、硬體平臺說
任何可存取 HTTP 之計算機皆可使用
3.2. 何處下載 SDK package 與安裝說明
不須下載,僅須透過 HTTP 存取網路服務即可 。
3.3.開發環境安裝說明
任何可存取 HTTP 之計算機皆可使用。
3.4.如何將 SDK package 與其它所需 component
不須加入任何 Library或 Reference,因網路服務放置於遠端主機。
3.5.如何 Build 所附之 sample code
所附的範例程式,原始碼資料如下圖所示:
包含 Visual Studio .NET 2010 的專案檔(sln),與原始碼存放資料夾
DriverRESTServiceSample。lib 存放顯示地圖用的動態連結函式庫(DLL),本專
案所使用的地圖元件為 GMAP.NET。若有需要可至
http://greatmaps.codeplex.com/ 下載最新版 DLL檔。
點選專案檔(sln),Visual Studio 會自行開啟整個專案。
http://greatmaps.codeplex.com/
按下 F5或編譯按鈕,即可編譯與執行程式。程式預設使用 Debug Mode,因
此,編譯完的執行檔將會放置於以下位置:
4.Sample Code 與流程說明
任何可存取 HTTP 資源的程式開發平台或程式語言,皆可利用本平台所提供之服
務開發應用程式。本節將以 .NET Framework 4.0 與 C# 為例,開發一個鄰近路
況資訊顯示應用程式。程式的存放位置為:
其程式執行畫面如下:
\GetFreshTelematicsPlatform\DriverRESTServiceSample\bin\Debug\DriverRESTServiceSa
mple.exe
\GetFreshTelematicsPlatform\DriverRESTServiceSample\bin\Debug\DriverREST
ServiceSample.exe
範例程式中,按下查詢按鈕,即可取得特定地點的鄰近路況資訊。
按下查詢按鈕後,其程式邏輯分為四大步驟:
1. 將使用者輸入,轉成服務存取位置
2. 送出服務請求
3. 將平台回應的 JSON String解析成路況事件物件。
4. 將路況事件顯示於使用者介面。
以下將對此四步驟的程式開發加以說明。
步驟一:將使用者輸入,轉成服務存取位置
使用者輸入經度、緯度、半徑資訊後,透過字串連結的方式,產生服務存取
位置。
步驟二:送出服務請求
透過 System.Net.WebClient 產生 HTTP Client 物件,並使用 DownloadString,
送出存取服務的 HTTP Request。DownloadString會回傳一個 string 物件,內含本
平台所回應的 JSON String。
步驟三:將平台回應的 JSON String解析成路況事件物件。
在 .NET Framework 4.0,提供 JavaScriptSerializer 類別,將 JSON String 直
接轉換成物件。因 JavaScriptSerializer 並非在預設時載入專案,因此需在參考
(Reference)加入 System.Web.Extensions.dll 後才可使用 JavaScriptSerializer。
首先將專案的 Target framework 改為 .NET Framework 4。
於Visual Studio 的 Solution Explorer,專案樹狀結構下的 References 按下右鍵,
並選擇 Add Reference…
選擇 .NET 標籤後再選擇 System.Web.Extensions,將 System.Web.Extensions.dll
載入專案中使用。
於程式碼前段使用 Using 宣告增加:
經過以上過程,程式即可直接宣告 JavaScriptSerializer ,將解析 JSON string,
解析成 .NET 物件。如以下範例:
using System.Web.Script.Serialization;
實務上,為了方便程式處理,會再將 object 物件陣列轉成自訂的物件。如本範
例程式將 JSON object 轉成 List 型態。
其 response 物件內,即包含多筆平台回傳的路況事件:
步驟四:將路況事件顯示於使用者介面。
因平台回傳的路況事件資訊,已轉換成 List 型態,因此可以很方
便的使用迴圈,搭配各種輸出方式,進行處理。
將平台回傳的資訊,使用迴圈,將事件結合成字串,並顯示於使用者 UI。
JavaScriptSerializer JSDecoder = new JavaScriptSerializer();
object Retobjs = JSDecoder.DeserializeObject(jsonString);
List response = new List();
response = JSDecoder.ConvertToType(Retobjs);
註:因範例程式碼使用多執行緒,將查詢過程與 UI分成不同執行緒執行,因此
使用了 Invoke 方式,在不同的執行緒上,更新 UI顯示內容。
將平台回傳的資訊,顯示於地圖 GMAP.NET地圖元件:
this.Invoke(new Action(() => ResTB.Text = EventInfo));
5. SDK 與 Function List API 說明
路況事件存取 API
路況事件存取 API,為一組網路服務。其網路服務為 REST (Representational
State Transfer) Service,因此不需使用 SOAP 或 XML-RPC 方式呼叫 API,僅須透
過 HTTP 協定,即可存取本平台所提供的路況事件。服務請求與回應的方式如
下。
1. 路況事件查詢服務請求(Request):
http://140.96.180.226:8513/DriverService/events/[latitude]/[longitude]/[radius]
請求參數 參數說明
[latitude] 查詢地點 – 緯度
[longitude] 查詢低點 – 經度
[radius] 查詢範圍 – 半徑 (公尺)
範例:查詢座標為 (25.043914, 121.529717),半徑 1500公尺內的路況事件與駕
駛行為:
http://140.96.180.226:8513/DriverService/events/25.043914/121.529717/1500
2. 路況事件查詢服務回應(Response):
當服務請求利用 HTTP 送出後,網路服務會根據使用者請求資訊,搜尋相關事
件,並以 JSON (JavaScript Object Notation)的形式回傳給客戶端程式。回傳的
JSON資訊 ,可能包含 0至多筆路況資訊。若查詢條件內,無搜尋到相關事件,
則會回傳空陣列 (Empty Array):
若查詢條件內,搜尋到一至多筆路況事件,則會回傳多筆路況資訊物件的陣列。
[]
[ {
"typeid" : 5,
"name" : "車體傾斜",
"count" : 18,
"lon" : 121.54420471191406,
"lat" : 25.041536331176758,
"lonlist" : [ 121.544, 121.54, 121.545, 121.54381, 121.540156, 121.54416 ],
"latlist" : [ 25.042, 25.0415, 25.04156, 25.0486, 25.046, 25.049 ],
"direction" : 90.65483093261719,
"val" : 9.159831285476685,
"unit" : "角度",
"datetime" : "2014-03-10 14:22:28.714"
},
{
"typeid" : 2,
"name" : "路面顛簸",
"count" : 30,
"lon" : 121.51942443847656,
"lat" : 25.04586410522461,
"lonlist" : [ 121.519, 121.519, 121.592, 121. 64, 121.595, 121.5195 ],
"latlist" : [ 25.08, 25.045, 25.045841, 25.045828, 25.0451, 25.045 ],
"direction" : 285.150146484375,
"val" : 2.743571102619171,
"unit" : "顛簸等級",
"datetime" : "2014-03-10 13:25:26.892"
}
]
路況事件物件屬性說明:
屬性 說明
typeid 路況事件的分類編號。
name 路況事件分類編號的顯示名稱。
count 本路況或駕駛行為事件,是由多少筆車輛資訊產生。即路況事
件產生的樣本數。數值越高代表越多車輛感測到同一事件。
lon 路況事件的中心點。(經度)
lat 路況事件的中心點。(緯度)
lonlist 路況事件的範圍。(經度)
由於各車輛感測的路況事件時的經緯度座標略有差異,且多數
路況並非單一座標點,為一個範圍。因此本平台提供加權過的
精簡路況範圍多邊形。此多邊形代表路況發生的範圍。
latlist 路況事件的範圍。(緯度)
lonlist 與 latlist 陣列的索引(index)具有對應關係。
即 lonlist[1] 與 latlist [1],可組成事件範圍多邊形內的一個點。
使用程式循序掃描後,可建立一個多邊形的事件範圍。
direction 路況發生時的車輛行車方向。以方位角(bearing)的方式顯示。數
值為 0~360度。正北方為 0度。正東方為 90.0 度。正西方為 270
度。可用此資訊來過濾不在使用者行經方向的路況資訊。
val 路況的強度或程度。不同路況會有不同的數值範圍。可由 unit
所提供的資訊判斷其意義。
unit 路況強度或程度的單位。
datetime 路況產生的時間點。
路況事件查詢服務請求與回應範例:
本服務採用HTTP 方式存取,因此可利用瀏覽器(Browser)測試請求與回應。
瀏覽器網址列輸入:
http://140.96.180.226:8513/DriverService/events/25.043914/121.529717/1500
瀏覽器取得服務回應:
6、參考資料
[1]REST, http://zh.wikipedia.org/wiki/REST
[2]JSON, http://zh.wikipedia.org/wiki/JSON
[3]GMAT.NET, http://greatmaps.codeplex.com/
http://zh.wikipedia.org/wiki/RESThttp://zh.wikipedia.org/wiki/JSONhttp://greatmaps.codeplex.com/