快速建構地圖服務（二） - 認識 HERE Data Hub CLI / API

進階功能：認識 HERE CLI、Data Hub API 與 Data Hub Console

什麼是 HERE CLI

CLI 的全名為 Command Line Interface，中文可以翻譯成「命令列介面」。所謂的命令列，指的就是以文字輸入命令進行操作的方式，因此 CLI 提供的是另一種有別於網頁介面的純文字模式。

純文字模式乍看之下會有點麻煩，但其實文字的方式可以跟程式語言結合，甚至寫成批次檔（Batch），只要把指令輸入就可以進行很多操作，不管是用手敲鍵盤還是用程式的方式自動執行。

需要注意的是：HERE CLI 需要安裝 Node JS 的環境才能執行。因此在開始前，請先下載並安裝它：https://nodejs.org/en/download

什麼是 Data Hub API

API 的全文是 Application Programming Interface，可翻譯成「應用程式介面」，乍看之下有點難懂，但您可以把您家的電視想成一個應用程式，上面有電源鍵、音量按鍵、選台按鍵、設定按鍵、HDMI 接頭，還有一個感應器，接收遙控器訊號，您可以把這些電視上的東西想成是 API。

API 是設計用來與應用程式互動的特定方式，例如您要把電視打開，就必須按下電源按鍵，而電源按鍵按下之後電視裡面的邏輯怎麼設計您並不需要了解，您只要知道按下電源按鍵之後，電視就會打開，然後可能會顯示 Logo，幾秒鐘之後電視畫面就出現了，這一連串設定好的動作是應用程式本身的邏輯，您不需要關心這些，您只要知道按下正確的按鍵會有什麼反應就好。

API 除了用來「得到」結果之外，也可以「輸入」您要的資訊，例如電視後面的 HDMI 接頭，也是「電視」這個應用程式的一個 API。HDMI 接頭只接受 HDMI 規格的接頭，把 HDMI 線的兩端連接好之後，另一端的影像輸出（可能是 DVD 播放器或遊戲機），只要輸入符合 HDMI 規格的影音內容，就會在電視上出現正確的影像。您不需要知道遊戲機裡面的程式怎麼運作，也不需要知道電視怎麼接收與解碼影像，您只要確保傳送到電視的訊號是正確的就好。

網路 API 概念圖，出處：https://bytenbit.com/best-guidelines-design-restful-api/

如果把這個應用程式部署在網路上開放給特定對象的話，您最常會聽到的是 HTTP GET、POST 與 PUT 請求：

• 輸入指令與參數（按下按鈕），得到結果（畫面與聲音）：這可以類比成 HTTP GET 請求。
• 輸入指令、參數與特定的內容（HDMI 訊號），得到結果（畫面與聲音）：這可以類比成 HTTP POST 或 PUT 請求。

認識 HTTP 請求：https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods

這就是 HERE Data Hub 之所以好用的地方，因為任何存放在 HERE Data Hub 的地圖資料，都可以透過 API 來進行操作，換言之，所有靜態的地圖檔，放上去之後就被賦予了動態更新的可能性。甚至您也可以使用 Data Hub API 來憑空建立您的地圖資料。有了 Data Hub API，您可以隨心所欲的使用您的地圖資料。

以我們剛剛建立的口罩地圖來說，您可以用 Data Hub API 來進行空間查詢（例如查詢某個地點附近的藥局），或屬性查詢（查詢某個行政區的藥局），或是進行統計，甚至是把所有的藥局資料轉成一個圖層放置到地圖上面。

剛剛所提到的 HERE CLI，其實底層也是把 Data Hub API 放進去，因此可以透過簡單的指令來進行操作。因為 API 的使用通常會需要一些程式設計的能力，因為 API 的本質就是讓程式之間互相溝通，如果不會寫程式的話很難發揮 API 本身的特色。

以難易度來說，使用 CLI 還是比使用 API 簡單一點。

什麼是 Data Hub Console

把資料放在網路上是非常危險的，不管是自己使用，或是開放給特定對象，甚至是無限制的開放給任意對象，我們都需要用權限來管理。

例如同一筆地圖，可能有些人負責維護，那我們就要給他們讀跟寫的權限；如果把這個地圖資料顯示在網頁上面，那可能就只需要讀取的權限就好，以免惡意人士透過 Data Hub API 竄改地圖的內容甚至把地圖刪掉。因此權限管理是非常重要的一步，我們一定要確保資料的安全性，才能無礙的提供流暢的地圖服務給使用者。HERE Data Hub 就透過 Token 的機制來進行權限的管理。

HERE 提供了非常容易使用的網頁介面來讓您進行權限的管理，就是HERE Data Hub Console。請您打開這個網頁：

https://xyz.api.here.com/token-ui/index.html

您需要登入才能繼續使用，按下「Sign In」，完成登入之後就會進入主畫面。主畫面的第一個分頁是Space Management，可以看到我們之前上傳的地圖檔「
scidm-maskdata_geo.csv」已經在裡面了。

接著請您進入「Access Management」，您會看到裡面已經有一些 Token 了，因為您之前已經有用過 Studio 來讀取，因此相對應的 Token 也會產生；如果您把這些 Token 刪掉的話，也可能造成之前建立的地圖無法運作，因此要針對 Token 進行任何的操作都務必要小心。

另外您也可以看到，Token 的種類分成暫時的「TEMPORARY」與永久的「PERMANENT」。我們可以針對不同目的的需求給予暫時或永久的權限，非常的方便。然而，請務必保護好您的 Token ，因為如果不該給的權限外流，是會對您在 Data Hub 上面的資料造成危險的。如果一旦發現 Token 外流，可能只能夠移除掉再建立新的，但這樣會對既有的服務與使用者造成很大的影響，不得不慎。

順道一提：目前您所看到的「TEMPORARY」Token，是登入 HERE Studio 的時候系統自動產生的，有效期限為一天，因此如果 HERE Studio 的網頁閒置太久的話，是會要求您再次登入的。

建立一個 Token

首先，在「Access Management」頁面上，按下左上角的「Generate Token」。

目前我們可以看到兩個選項，第一個是「ALL」，第二個是我們之前上傳的「scidm-maskdata_geo.csv」。「ALL」顧名思義就是全部，給了這個權限就會套用在您的帳號下所有的 Space 上面，因此必須要小心。您也可以選擇設定一個特定的 Space 的權限。

而我們可以設定的權限分成：

1. manageSpaces：管理 Space，如新增 Space、刪除 Space。
2. readFeatures：讀取 Space 的內容（Features）。
3. createFeatures：在 Space 中增加內容（Features）。
4. deleteFeatures：刪除 Space 的內容（Features）。
5. updateFeatures：修改 Space 的內容（Features）。
6. ALL：全部的權限。

要怎麼決定選擇哪一個權限呢？這個要看您的用途，以及 Space 存在的目的。例如我們可以這樣子理解：

• 您寫了一支 APP 用來追蹤貨物的流向，貨物上面裝有 GPS 追蹤器，而您建立了一個 Space 存放貨物的軌跡，您也寫了一支程式在追蹤器上面，每分鐘會上傳一次 GPS 位置與時間戳記，因此這支程式的權限應該給予「createFeatures」，因為它只負責上傳資料到 Space ，而不需要讀取內容，更不需要刪除內容。因此即使這個 Token 外流，Space 的資料也不會有任何被刪除或清空的風險（但有可能會被惡意丟進錯誤或垃圾資料）。
• 這支 APP 也必須連到 HERE Data Hub 去讀取 Space 的內容，並且把這個貨品最後的位置與軌跡畫在地圖上，因此這個 APP 需要有「readFeatures」的權限，做純粹的讀取動作，而不需要對 Space 上面的資料有任何的更動行為。即使這個 Token 外流了，我們也可以確保他只會看到 Space 的內容，而無法去更動裡面的內容，進而保持了一定的安全性。
• 物流公司想要設定地理圍籬（Geofence）來知道貨物是否已經送到目的地，他們必須要能夠設定想要的地理圍籬。因此我們必須先建立一個 Space 來存放地理圍籬（可能是多邊形），並且給予這支 APP 「readFeatures」、「createFeatures」、「deleteFeatures」、「updateFeatures」的權限，因為這樣物流公司才可以讀取、設定、刪除、以及修改地理圍籬。

您應該可以想像出更多有趣的使用場景，而 HERE Data Hub Console 給了您很靈活的選項來設定適當的權限。而為了之後的課程，我們必須先建立一個「ALL」權限到「ALL」，這代表最高等級的權限，因此請務必謹慎。按下「ALL」的「ALL」，全部的選項都會被勾選，代表這允許所有操作。按下「Next」之後會請您確認是否使用到付費功能（Add-on），目前是免費帳號所以用不到，請直接按「Next」。

最後，會請您設定這是屬於暫時的「TEMPORARY」或永久的「PERMANENT」，請選擇「PERMANENT」，下面的「DESCRIPTION」您可以輸入一些備註，另外「ALLOWED ORIGINS / HOSTS ( ENTER ONE IN A LINE )」您可以限制這個 Token 只能使用在某些網域或 IP 位址。目前我們是不需要，但如果您是會用這個 Token 來部署網路服務或是限制特定的使用對象（例如某特定 IP 才能夠讀取這個 Space），就可能會需要。最下方會顯示您的帳號與 APP ID。

設定完之後請按下「Submit」。

接著您就可以看到剛剛設定的最高等級權限 Token 已經產生了。我們之後的課程會使用到這個 Token。

下一步請您自己建立一個「scidm-maskdata_geo.csv」的「readFeatures」Token，只要給予讀取的權限就好。請記下這個 Token，待會討論 API 的時候會使用到。

體驗 HERE CLI

安裝 HERE CLI

HERE CLI 官方網站：https://developer.here.com/documentation/studio/map_customization_suite_cli_hlp/dev_guide/index.html

安裝好 Node JS 環境之後，請打開您的命令列模式（Command Prompt）或終端機（Terminal）。以 Windows 的作業系統來說，我覺得最快的方法應該是按下 「WIN+R」 來叫出輸入指令的對話框，輸入「cmd」之後按下 「Enter」 就可以；在 Mac OS 的環境按下「cmd+space」，然後輸入「term」之後按下「Enter/Return」就可以。以下範例為 Windows 作業系統。

之後您就會看到一個黑色的視窗，閃爍的游標就是可以輸入文字的位置。請輸入以下指令之後按下「Enter/Return」：

npm -v

這個步驟只是為了要確保 Node JS 以及 npm （Node JS 的套件管理） 已經成功安裝，如果他顯示出一串數字代表成功了。如果成功了，請輸入以下指令：

npm install -g @here/cli

npm 會自動下載需要的檔案並安裝，安裝成功它會告訴您「added xxx packages from xxx contributors in xx.xxs」，就是完成了。

HERE CLI 基本指令

接著我們就需要在 HERE CLI 裡面設定我們的帳戶資料，這個動作通常只需要做一次就好。在命令列輸入以下指令：

here configure account

輸入完之後他會要求您登入您在上一個章節申請的 HERE 開發者帳號，輸入 email 之後按下「Enter」，之後輸入密碼（不會列印在螢幕上）之後按下「Enter」，確認無誤之後就會登入，並保存登入資訊，因此下一次開啟不用再登入一次。

到這邊就完成設定了！

因為我們之前已經有上傳一個地圖資料過，我們就來看一下怎麼使用 HERE CLI 來顯示這個地圖資料。首先先輸入以下指令：

here xyz list

這邊可以看到螢幕上面列印出了一個表格，以我這邊的範例來說，口罩地圖的資料 ID 是 「z4nk5sMV」，檔名是「scidm-maskdata_geo.csv」，如果您有印象的話，這跟之前在 HERE Studio 裡面看到的是一樣的。

這個 ID（以下我們稱 Space ID）很重要，每一個上傳的地圖檔（以下稱為 Space）都會有一個獨特的 ID，因此即使是同一筆資料，不同的使用者上傳拿到的 Space ID 也不一樣，因此您看到的結果絕對不會跟我一樣。我們也可以透過 CLI 來查閱這個 Space ID 的內容為何，請輸入以下指令

here xyz show SPACE_ID （請把「SPACE_ID」換成您自己的 Space ID）

從螢幕上可以看到它列出了所有這個 Space 裡面所有資料的基本屬性，不過因為是純文字所以不太好閱讀，因此我們換個方式，請輸入以下指令：

here xyz show -w SPACE_ID （請把「SPACE_ID」換成您自己的 Space ID）

指令執行完之後，他會在您的瀏覽器裡面開一個新的頁面，並且顯示「z4nk5sMV」這個 Space 的內容。您可以在地圖上面進行平移與縮放，也可以切換地圖模式，也可以點選地圖上的標記（就是您上傳的資料點位）來查閱內容。右邊的文字則是這個 Space 的原始碼，為 GeoJSON 格式。

如此一來，透過 HERE CLI，我們就不一定要透過 Studio 才能看見 Space 的內容，非常的方便！而且其實這個網頁的網址，也可以直接分享給別人瀏覽。

除了單純的顯示之外，我們也可以用條件式的方式過濾 Space 的內容，只留下我們要的部份，例如我們可以只顯示南投縣埔里鎮衛生所的資料，就可以用以下的指令：

here xyz show -w SPACE_ID -s "p.醫事機構名稱=南投縣埔里鎮衛生所" （請把「SPACE_ID」換成您自己的 Space ID）

參數「-s」是搜尋的意思，這個指令意思就是要搜尋「醫事機構名稱」等於「南投縣埔里鎮衛生所」的資料，如果輸入錯誤的話，就會回傳空的資料。在欄位名稱前面一定要加上「p.」。

條件式支援 =（等於）、!=（不等於）、>（大於）、>=（大於等於）、<（小於）、<=（小於等於）等運算子。如果欄位值是字串的話，只能夠用 = 或 != 來比對，沒辦法進行模糊比對，也不支援萬用字元或Regex。如果資料值的型態不是整數或浮點數的話，也不能夠進行 >、>=、<、<= 等計算。

例如在這個 Space 中如果計算口罩數量是不會成功的，因為從原始碼（如上圖）中可以看出所有的屬性都是字串型態（這是 CSV 格式的缺點：無法定義欄位格式），因此即使執行了以下指令，也會回傳全部的資料：

here xyz show -w SPACE_ID -s "p.兒童口罩剩餘數>3000" （請把「SPACE_ID」換成您自己的 Space ID）

如果要克服這個問題，那就必須在上傳之前針對屬性資料做轉換，把「兒童口罩剩餘數」跟「成人口罩剩餘數」的型態都改成整數，這樣才可以進行運算。這邊就先略過不提這部份。

使用 HERE CLI 也可以刪除某個 Space 或清空某個 Space 的內容，不過使用時請勿必小心再小心、確認再確認，因為清空跟刪除都是不可逆的，一旦執行是無法挽回的。

• 刪除：here xyz delete SPACE_ID
• 清空：here xyz clear SPACE_ID

關於所有的指令參數與說明，請參閱：https://developer.here.com/documentation/studio/map_customization_suite_cli_hlp/dev_guide/topics/commands.html

使用 HERE CLI 動態更新地圖

稍微用一點小訣竅，就可以在不寫程式的狀況下，動態更新您的地圖。

打開瀏覽器，開啟我們之前下載口罩地圖的網頁：https://scidm.nchc.org.tw/dataset/nhi-maskdata

找到之前下載過的「scidm-maskdata_geo.csv」，按下右邊的「探索」，接著在「下載」上面按下右鍵，選擇「複製連結」或「複製連結位址」（可能會是其他類似的名稱）。

如此一來，這個檔案的下載連結就已經複製到剪貼簿了。接著，請打開 cmd，輸入以下指令：

cd Desktop

這會把目前工作的目錄改成您的桌面，接著請輸入：

curl -o mask_data.csv https://scidm.nchc.org.tw/dataset/nhi-maskdata/resource/6116b06b-9c88-4b63-80f9-3f65c7da1370/nchcproxy

這個指令會下載「scidm-maskdata_geo.csv」，存在桌面，檔名為「mask_data.csv」。經檢查確實是最新的檔案。

接著會需要用 HERE CLI 把新的檔案上傳到之前建立的 Space 把之前的紀錄覆蓋掉，但如果直接上傳，舊的資料不會被覆蓋，反而會直接加入新的資料，這不是我們想要的，因此我們必須先把之前上傳的口罩地圖清空。

在 cmd 中輸入以下指令：

here xyz list

確認 Space ID 之後，輸入以下指令：

here xyz clear {SPACE_ID}

接著會要求您確認是否要把 Space 清空，請輸入「y」並按「Enter」。

現在原本的 Space 還在，但內容已經空了，我們現在要把剛剛下載的 mask_data.csv 上傳到我們已經清空的 Space。請先確認工作路徑是否為桌面（Desktop），接著輸入以下指令：

here xyz upload {SPACE_ID} -f mask_data.csv

上傳的進度會顯示在螢幕上，完成之後也會顯示總共上傳的資料筆數（目前為 5961 筆）。

接著我們打開之前製作的地圖，可以看到上面的資料也被更新到我們剛剛下載的最新版本了。

所以，我們剛剛總共有三個關鍵的指令：

1. 下載最新的口罩資料。
   curl -o mask_data.csv https://scidm.nchc.org.tw/dataset/nhi-maskdata/resource/6116b06b-9c88-4b63-80f9-3f65c7da1370/nchcproxy

2. 清空原本的 Space 內容，不過我們可以加上一個「--force」的參數來強迫進行，這樣就不會被要求輸入「y」，以節省時間。
   here xyz clear {SPACE_ID} --force

3. 上傳剛剛下載的最新口罩資料。
   here xyz upload {SPACE_ID} -f mask_data.csv

只要重複這個步驟，就可以更新您的口罩地圖了。

體驗 HERE Data Hub API

Data Hub API 說明文件：https://developer.here.com/documentation/studio/api-reference-swagger.html

Data Hub API 初體驗

我們可以使用 Data Hub API 來列出一個 Space 的全部內容，請使用您的瀏覽器打開下面這個網址（請換成您 scidm-maskdata_geo.csv 的 Space ID 與具有讀取權限的 Token）：

https://xyz.api.here.com/hub/spaces/{SPACE_ID}/iterate?access_token={TOKEN}

如果您使用的是正確的 Space ID 與 Token，您應該會看到類似下面這個畫面，這個畫面就是使用 Data Hub API 得到的回傳結果，使用的是「iterate」這個 API，功能是回傳 Space 裡面的資料，因此如果資料量愈大，就需要愈多的時間。回傳的格式是 GeoJSON。

另外，我們也可以用 API 的方式取得統計數據，使用的是「statistics」這個 API：

https://xyz.api.here.com/hub/spaces/{SPACE_ID}/statistics?access_token={TOKEN}

有些瀏覽器會把 JSON 格式重新排版，有些不會。如果您覺得這樣的格式不好閱讀，網路上有很多免費的服務可以把 JSON 格式重新排版過，例如：https://jsonformatter.org/ 。我們可以把上一個畫面中的文字全部複製之後貼到這個網站的左側文字框，排版過的美觀版本就會在右邊出現。

我們也可以使用 Data Hub API 來查詢我們剛剛用 CLI 查詢過的「南投縣埔里鎮衛生所」的資料，使用的是「search」這個 API：

https://xyz.api.here.com/hub/spaces/{SPACE_ID}/search?p.醫事機構名稱=南投縣埔里鎮衛生所&access_token={TOKEN}

除了用屬性查詢外，我們也可以用地理空間的方式查詢，例如我們可以查詢台北車站（經度：121.5170534，緯度：25.0478554）週邊一公里（1000 公尺）內所有的醫事機構，使用的是「spatial」這個 API：

https://xyz.api.here.com/hub/spaces/{SPACE_ID}/spatial?lon=121.5170534&lat=25.0478554&radius=1000&access_token={TOKEN}

我們也可以使用 Data Hub API 來取得這個 Space 在地圖上某個區塊的內容，在網路地圖的架構中，我們經常使用 X 座標、Y 座標、Z 階層來表示地圖上某個區塊（Tile）。

詳細資訊可參閱：https://en.wikipedia.org/wiki/Tiled_web_map

例如 X = 856、Y = 440、Z = 10 的區塊，大概是雪霸國家公園的位置：https://a.tile.openstreetmap.org/10/856/440.png

我們就用這個區塊來看看裡面有沒有醫事機構，使用的是「tile」這個 API：

https://xyz.api.here.com/hub/spaces/{SPACE_ID}/tile/web/10_856_440?access_token={TOKEN}

答案是有的，是「臺中市和平區梨山衛生所」。

我們之後的課程會使用 Data Hub API 結合 JavaScript 的地圖框架來實做出一個網路地圖。

「快速建構地圖服務」系列文章

快速建構地圖服務（一） - 認識 HERE Studio / Data Hub
快速建構地圖服務（二） - 認識 HERE Data Hub CLI / API
快速建構地圖服務（三） - 使用 QGIS 玩轉 HERE Data Hub
快速建構地圖服務（四） - 當 Leaflet JS 遇見 Data Hub
快速建構地圖服務（五） - 整合 HERE 地點搜尋 API
快速建構地圖服務（六）- HERE Waypoints Sequence 路徑最佳排序
快速建構地圖服務（七）- 認識 HERE Routing API - 路徑規劃
快速建構地圖服務（八）- 認識 Matrix Routing
快速建構地圖服務（九）- Isoline Routing
快速建構地圖服務（十）- HERE Tour Planning 物流路徑預排與成本精算
快速建構地圖服務（十一）- HERE Route Matching GPS 軌跡分析
快速建構地圖服務（十二）- HERE Custom Locations 地圖資料倉儲與查詢
快速建構地圖服務（十三）- HERE Geofencing 地理圍籬
快速建構地圖服務（十四）- HERE Custom Routes 自建路網 + Vector Tile 向量圖磚 + Map Image API 靜態地圖
快速建構地圖服務（十五）- HERE Positioning 網路定位服務