REST API來源：https://en.wikipedia.org/wiki/Representational_state_transfer

總的說來，要使用REST API，就需要向服務器發出HTTP請求，服務器會按已知的格式給我們返回答案，比如JSON或XML。

虛幻引擎擁有兩個非常實用的插件：

Http Blueprint – 向服務器發送HTTP。

JSON Blueprint Utilities – 解析和解碼JSON對象。

這些插件在C++和藍圖中公開了它們的功能，不用編寫代碼就可以查詢這些API！

初始設置

設置谷歌云（Google Cloud）服務

要使用REST API，通常需要個人API密鑰（Personal API Key）。

這個密鑰會識別請求的來源，以便在出現與服務相關的費用時，根據你的使用情況收取費用。

使用這些服務必須有谷歌地圖API密鑰。參閱此處了解關于密鑰創建的更多信息。

對本實驗而言，我們在項目密鑰（Project Key）中添加了以下API：

• 地圖瓦片API（Map Tile API） – 使用Cesium for Unreal插件加載3D瓦片內容
• 地圖地點API（Maps Places API） – 查詢地點信息
• 地圖海拔API（Maps Elevation API） – 了解某一位置的海拔數據

發送請求時要小心，因為有可能產生相關成本。請避免在循環中發送請求，因為這樣有可能超過每秒查詢數的限制，還有可能造成成本浪費。為此，設置API密鑰限制和使用警報非常重要。

創建虛幻項目

新建一個虛幻引擎5.1項目，在模擬類別（Simulation Category）中選擇空白項目模板，僅使用藍圖。

打開編輯器之后，啟用以下插件

• Cesium for Unreal（可從虛幻商城獲取）。
• Http Blueprint（它會自動向Json Blueprint Utilities添加一個依賴項）

在模擬模板中啟用SunSky和GeoReferencing插件。
然后，你要將Photorealistic 3D Tiles添加到關卡中。

Cesium在本教程中記錄了該過程。遵循其中描述的步驟，但是有以下例外情形：

• 不需要使用Cesium Sunky，模擬模板已經設置好虛幻引擎SunSky。
• 不要使用Cesium動態Pawn（Cesium Dynamic Pawn）。我們使用GeoReferencing插件提供的BP_RoundPlanetPawn。

確保為以下內容設置相同的地理參考點：

• Cesium地理參考（Cesium Georeference）
• 虛幻引擎地理參考系統（UE Georeferencing System）
• SunSky

這一步是必須要做的，因為三個插件各自獨立運行，我們不想在它們之間創建依賴關系。

確保所有地理參考對象都同步

玩家出生點在巴黎凱旋門附近

下面我們就來使用API

創建需要的資產

設置基本游戲對象

確保：

• 關卡中有一個玩家出生點
• 有可以使用的自定義游戲模式設置
  • 你自己的玩家控制器（我們使用修改過的BP_SimPlayerController副本）
  • Georeferencing插件中有可用的BP_RoundPlanetPawn在項目設置中設置以下游戲模式和初始地圖。

設計顧慮

在這個演示項目中，我們實現了3個主要功能

• 自動完成位置搜索并飛到該位置
• 查詢附近的興趣點（餐館、酒吧），生成地理標記（GeoMarker）
• 點擊地理標記獲取詳細信息。

3個主要功能
為了實現這些功能，我們創建了以下對象：

• BP_PlaceAPI_Helper：負責調用谷歌地圖API的藍圖Actor
• BP_Place：存儲地點（位置）屬性的純藍圖數據對象
• UMG_GeoQueries：主應用程序UMG控件
• BP_GeoMarker：作為地點視覺表示的藍圖Actor
• BP_MarkerManager：用于管理地理標記的藍圖Actor

使用REST API要注意的主要問題是，發送請求是一個非阻塞調用。調用者將在之后收到請求結果，我們不希望在等待請求結果的過程中阻塞程序。因此，我們將使用大量的異步編程模式，利用事件分發器。

自定義事件VS函數

在使用Http發布請求節點（Http Post Request Node）發布請求時，你可以在右上角看到一個小時鐘。這意味著該節點將執行異步調用。事件圖表將在這里暫停執行（除非在請求處理（Request Processing）引腳連接其他內容）。收到結果后，它將通過“請求成功（Request Was Successful）”或“請求不成功（Request Was Not Successful）”執行引腳恢復執行。

發布請求是一個異步調用！

這會帶來了一個重要的設計約束。函數中不能包含任何帶異步調用的藍圖節點。只能在事件圖表中使用。因此，你必須在一個事件圖表中、在一個自定義事件中發送請求。

但是如果在事件圖表中實現所有內容，整個圖表很快就會變得非常混亂。因此，我們仍然使用函數將同步操作（例如構建請求和處理應答）組合在一起，然后將這些調用堆疊在自定義事件下。

誰知道誰？在對象之間創建引用的正確方法！

另一種常見的重大設計缺陷在于用戶界面和底層對象的綁定方式。

在應用程序編程中，我們有不同的設計模式，包括文檔/視圖、模型-視圖-控制器（MVC）、模型-視圖-視圖模型（MVVM）。

無需輸入太多細節，表示層（UI）知道它所顯示的對象，但對象本身必須對表示層不可知。

從數據對象（如BP_PlacesAPI_Helper對象）調用控件更新是非法的！

建議讓BP_PlacesAPI_Helper在數據可用或發生更改時觸發事件。因此，我們要創建“事件分發器”，其他應用程序對象，比如UMG控件或玩家控制器將訂閱事件分發器！

所有可能的請求都將遵循類似下面的模式：

請求的剖析

注意，搜索附近地點功能有一個小技巧：為了限制服務器的負載，請求只返回前20個結果。

要想獲取更多結果，需要重新發起相同的查詢，但這次有一個特殊選項，就是和第一個查詢結果一起收到的token。這樣就可以得到后續的20個地點，以及再往后的20個地點，最多60個地點。

為了處理這種特殊情況，我們有兩個針對附近地點的事件，一個用于獲取前20個地點，另一個用于獲取后續的20個地點。

聚焦BP_PlacesAPI_Helper Actor

根據上面闡述的設計，BP_PlacesAPI_Helper將包含下列成員：

• 在事件圖表中：主入口點函數

• 自動完成地點尋找（Find Place Autocomplete）
  • In：部分地址，Out：預測的BP_Places數組
  • 完成時，事件分發器“PredictedPlacesAvailable”
• 查詢地點詳情（Query Place Details）
  • In：BP_Place, GetAltitude（可選）。Out：更新輸入BP_Place
  • 完成時，事件分發器“Place Details Received”
• 搜尋附近地點（Search Nearby Places）
  • In：類型字符串、半徑，Out：附近BP_Places數組
  • 每當收到一批地點時，事件分發器“Nearby Places Received”
• 作為函數

• 格式化請求URL的函數
• 處理JSON結果的函數
• 效用函數
  • 凈化URL（用%20替換空格，用%2C替換逗號）
  • 檢查JSON響應中的錯誤

BP_PlacesAPI_Helper函數

BP_PlacesAPI_Helper變量和事件分發器

格式化請求

API文檔中有關于格式化請求的解釋。

例如，從地點自動完成API（Places Autocomplete API）文檔中，我們了解到URL必須按這種方式格式化，可能的其他輸入參數要用“?m=value”隔開。

URL格式

URL示例

大多數時候，我們只是附加字符串，最后是我們的API密鑰。

查找海拔請求

發送請求

Post Request需要一個URL和說明這是一個JSON請求的請求頭。

如果需要添加其他可選參數，可以提供一個可選的請求體。

注意，我們為實際請求發送統計添加了計數器，用于監控實際發送的請求數量。

發送請求（注意異步調用）

處理結果

處理結果是整個過程中最枯燥的部分。

你將收到一個采用通用編碼方式編碼的JSON對象。

你可以請求一個字段值，你將得到：

• 一個帶值的字符串，如果是“葉節點（Leaf Node）”。
• 又一個JSON對象，如果是“子節點（Child Node）”。
• 其他JSON對象的數組，在循環中處理。

所有這些情況都由“獲取字段（Get Field）”藍圖節點處理。

你要知道結果的格式，以便處理結果。好在它會被記錄下來。

專業意見：在嘗試迭代解析之前，最好先在瀏覽器中輸入請求URL來運行查詢。如果JSON對象以字符串形式返回，會難以讀取。

但是有些在線JSON查看器，比如這個，你可以將這個字符串粘貼到這個查看器中，它會創建一個更容易讀取的節點層級！

原始JSON響應字符串

在線查看器中顯示的相同JSON字符串

這種表示方式更便于在層級結構中導航，也更容易了解獲取字段節點是需要返回一個字符串，還是另一個JSON對象或一個JSON對象數組。

在創建獲取字段節點時，數值（Value）引腳默認顯示灰色。它會根據你連接的引腳發生改變。因此，在連接引腳之前，必須先創建包含目標引腳的節點。

始終將數值引腳從目標綁定到源，以獲得正確的類型！

由于JSON的結構一目了然，并且知道獲取字段的規則，解碼響應就變得非常簡單，比如下面的“查找地點自動完成（Find Place Autocomplete）”。

注意，在生產中，建議在處理過程中采用更好的錯誤處理流程。

JSON文件處理示例

處理過程的最后一步是將結果通知給感興趣的對象。

我們事先不知道誰會對結果感興趣。可能是顯示地點細節的UI，然后由玩家控制器決定是否讓Pawn飛到這個位置。

為此，我們添加了一個事件分發器，其中可能包含將隨事件傳遞的輸入，訂閱該事件的其他對象將接收該輸入。

在BP_PlacesAPI_Helper中，我們在處理完結果之后觸發事件分發器

在UMG控件中，我們訂閱了這個事件，并相應地重新構建了建議列表。

用戶界面

除了ListView系統之外，UMG控件并沒有什么特別之處。

在UMG中，使用控件填充垂直框是一個非常常見的操作。但是根據元素的數量，具體過程可能比較復雜或者比較緩慢。ListView是一個虛擬視圖，可以幫助我們處理列表中的大量對象，具有很大的靈活性。

• 為列表的每一行創建一個特殊控件。
• ListView將專門用于這個控件。
• 在向列表中添加元素時，該元素會被傳輸到行控件用于顯示。

為了整理這個列表，我們需要：

• 創建一個UMG用戶控件（UMG User Widget）作為行控件。（這里是UMG_PlaceWidgetEntry）
• 在本POC中只是個簡單的文本框，但它可以包含一個圖標。
• 在“圖表（Graph）”面板中，點擊“類設置（Class Settings）”，在細節面板中找到“接口（Interfaces）”類別，將“用戶對象列表條目（User Object List Entry）”添加到已實現接口列表中。
• 右鍵單擊“列表項目對象集上（OnListItemObjectSet）”，選擇實現事件。
• 在藍圖圖表中，將這個對象轉換為需要顯示的實際類型，然后用它的屬性來更新UI。

行控件（Row Widget）需要實現“用戶對象列表條目”接口。

需要實現“列表項目對象集上”事件。

然后，在主控件上添加一個列表視圖控件（ListView Widget），將條目控件類（Entry Widget Class）設為剛才創建的類。每當向列表中添加一個項目，就會創建相應的行控件，顯示底層對象。

將點擊項目（Item Clicked）事件綁定到一個自定義事件處理器上，這樣處理就結束了。

定義與每一行相關的控件類（Widget Class），綁定點擊項目事件。

事件處理器負責填充列表，對點擊做出響應。

地理標記及其管理器

地理標記藍圖由一個簡單的縮放立方體、一個用于顯示大頭釘的自發光材質和一個2D文本控件構成。

大頭釘稍微有點特殊，我們將根據距離對它進行縮放，以呈現單像素線條的效果。

在我們的例子中，如果使用3D瓦片，在下載瓦片時，幾何體將隨著時間的推移不斷改進。為了確保始終正確對齊，2s定時器會將控件重新放在地平面上。

按距離縮放大頭釘網格體

限制在地平面上（使用海拔高度偏移）

確保控件組件（Widget Component）使用你的自定義控件，

并在“屏幕”模式下按“期望的大小”呈現。

為了實現交互性，2D控件包含一個帶鼠標鍵按下綁定的換行邊界，

它會發送一個“Clicked”事件分發器。（可以是一個透明的按鈕）

在處理多個這樣的對象時，一種明智的做法是創建一個專門的對象來管理這些對象。在這種情況下，標記管理器（Marker Manager）非常簡單，它只處理一組標記類型，但可以發展到處理不同的標記層，帶可見性開關……

創建一個BP_MarkerManager Actor，一個生成地理標記（SpawnGeoMarkers）事件。在這個事件中，我們要：

• 移除所有現有標記，
• 獲取樣式信息（見下文）
• 計算變換（向上向量不是Z+，我們在圓形的地球上）
• 生成標記
• 設置屬性
• 綁定事件“Clicked”，該事件將發送標記與BP_Place 

刪除標記時，一定要取消綁定事件“Clicked”！

生成標記1/2

生成標記2/2

樣式

在啟動這樣的應用程序時，我們事先不知道會給標記使用哪種顏色（Colors）或圖標（Icons）。隨著時間的推移，我們可能還會添加其他類型的標記。如果開始對這些值進行硬編碼，之后的編輯過程將會十分痛苦。

要解決這個問題，數據表是一個非常好的選擇。

• 利用顏色和圖標屬性創建一個簡單的S_MarkerStyle。
• 基于這一結構創建數據表，并為你希望提供支持的標記類型添加行。
• 將這個數據表設為BP_MarkerManager的屬性（Property）。
• 在生成標記時，管理器將使用這些數據來選擇樣式。通過這種方式，你可以逐漸改進自己的樣式，甚至為最終用戶提供不同的自定義樣式！

基于樣式內容構建數據表

玩家控制器處理高級邏輯

現在，MarkerManager和PlaceAPI Helper可以在事情發生時發送事件，接下來我們要處理邏輯。

這是在玩家控制器中完成的，它會生成UI并獲取對MarkerManager和PlaceAPI Helper的引用。

綁定地點相關事件

綁定標記相關事件

總結

通過Http藍圖和JSON藍圖實用程序，在虛幻引擎中使用Web API變得越來越容易。

借助這些模塊，所有人都可以使用這些API，不需要編寫代碼。

由于請求的異步性，采用事件驅動型設計非常重要，但是通過事件分發器和將回調綁定到這些事件上，一切就簡單多了。

這個簡短的概念驗證過程是在一天內完成的，還有很多地方需要改進。但我們的目標是說明查詢外部服務其實非常容易，而這也是數字孿生應用程序的關鍵一環！

希望大家喜歡！

文章轉自微信公眾號@虛幻引擎