開放式車載雲端服務管理平台 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/