使用 Groovy 呼叫外部 REST API

簡介

本教學課程示範如何從 Oracle EPM Cloud Planning 中的 Groovy 指令碼呼叫外部 Rest API。您也將瞭解如何使用功能表項目來呼叫命令檔，以及如何將動作功能表與資料表單建立關聯，來建立滑鼠右鍵動作功能表。

背景

Groovy EPM 物件模型提供呼叫內部 (跨 POD 或其他 Oracle Cloud Services) 和外部 REST API 的方式。在此範例中，您可以建立並執行 Groovy 規則來呼叫外部 Google Places REST API，以在 ManageEmployees 表單中新增或更新員工地址資訊。

必要條件

Cloud EPM 實作教學課程可能需要您將快照匯入您的 Cloud EPM Enterprise Service 例項。您必須先要求另一個 Cloud EPM Enterprise Service 例項或移除目前的應用程式與業務程序，才能匯入教學課程快照。教學課程快照不會透過您現有的應用程式或業務程序進行匯入，也不會自動取代或還原您目前使用的應用程式或業務程序。

開始此教學課程之前，您必須：

讓服務管理員可以存取 Cloud EPM Enterprise Service 例項。
上傳此快照並匯入至您的 Planning 例項。如果您先前已上傳另一個 Groovy 教學課程的快照，您可以繼續使用相同的快照。
您必須先註冊並建立計費帳戶以取得 API 金鑰，才能開始使用包含此教學課程中所使用之 Places REST API 的 Google Maps 平台 API。若要深入瞭解，請參閱 Google Maps Platform 入門。

附註：

如果匯入快照時發生移轉錯誤，請重新執行移轉 (不包括 HSS-Shared Services 元件)，以及「核心」元件中的「安全性與使用者偏好設定」人工因素。如需上傳與匯入快照的詳細資訊，請參考管理 Oracle Enterprise Performance Management Cloud 的移轉文件。

秘訣：

此教學課程所需的命令檔會連結為每個區段內的文字檔。

載入 Planning 計算變數

在此區段中，您可以從 XML 檔案上傳計算變數，以用於 Groovy 指令碼。

在 HP4_Plan2_Variables.xml 的連結上按一下滑鼠右鍵，然後將檔案儲存至本機磁碟機。
從左上方，按一下導覽器，然後導覽至規則 (在「建立和管理」底下) 以開啟 Calculation Manager。在「系統檢視」中，展開 EPM Cloud > HP4 。在 Plan2 上按一下滑鼠右鍵，然後選取匯入。
在「檔案匯入詳細資訊」下，瀏覽從本機磁碟機選取 HP4_Plan2_Variables.xml 。
在「地點明細」下進行下列選取：

應用程式類型：EPM Cloud
應用：HP4
立方體：Plan2

在「匯入選項」下，選取覆寫現有物件。

按一下匯入。複查匯入結果，然後按一下確定。
按一下取消，關閉「匯入」對話方塊。

在 Planning 中建立具名連線

在此區段中，您可以編輯現有連線以包含 Places REST API 金鑰。

瀏覽至連線 (在「工具」底下)，然後選取位置連線。

在金鑰參數中輸入 API 金鑰來編輯連線。儲存並關閉連線。

建立 Groovy 程序檔

在此區段中，您會實作 Groovy 指令碼來更新員工地址。我們將使用預先定義的 ManageEmployees 表單。

在 Calculation Manager 中，在 Plan2 立方體中建立名為 Groovy 新增或更新員工地址的規則。

在「規則編輯器」中，將「設計工具」選項變更為編輯命令檔，然後將「命令檔類型」設為 Groovy 命令檔。

複製此命令檔並貼到編輯器中：

/*RTPS: {Employee} {EmployeeAddress} {Scenario} {Year} {Period} {Entity} {Version}*/ 
Member employee = rtps.Employee.member  

// Get the complete address using the Google maps REST API. Use the original if Google maps can't find the address
def address = rtps.EmployeeAddress  
HttpResponse<String> jsonResponse = operation.application.getConnection("Places")
.get()
.queryParam("input", rtps.EmployeeAddress.enteredValue)
.asString()  
println(jsonResponse.body)  
ReadContext ctx = JsonPath.parse(jsonResponse.body) 
if(ctx.read('$.status') == "OK") 
	address = getTextCellId(ctx.read('$.candidates[0].formatted_address') as String, true) 

// Generate the calc script to save the employee address
"""SET CREATENONMISSINGBLK ON;
FIX(${fixValues(rtps.Scenario, rtps.Year, rtps.Period, rtps.Entity, rtps.Version, employee)}, "USD")
    "Employee Address" = $address;
ENDFIX;"""

定義此規則在第一行所使用的全部執行時期提示 (RTP)。

取得 Employee RTP 指定之 employee 的「成員」物件。

指派在 EmployeeAddress RTP 中輸入的文字作為 address 的預設值。

取得「位置」連線，以對此資源執行 HTTP GET 要求，並傳送在 EmployeeAddress RTP 中輸入的文字作為 input 查詢參數的值。

附註：

Places 連線物件是 Groovy 指令檔與 Google Places REST API 資源之間的通訊連結。

記錄 Google Maps REST API 回應以進行除錯。

剖析使用 JsonPath 程式庫從 API 收到的 JSON 回應。如果狀態 == OK，請從傳回陣列中的第一個候選物件讀取 formatted_address 欄位，取得 formatted_address 的文字儲存格 ID，然後將其指派給地址。

產生計算指令碼以儲存此員工地址。

在工具列上，按一下 (儲存) 以儲存命令檔。

附註：

儲存命令檔會在「變數」頁籤中顯示變數。

您只想讓使用者輸入 EmployeeAddress 的值。在「變數」頁籤中，針對員工、實體、期間、案例、版本和年度選取隱藏。

附註：

當使用者從表單執行指令碼時，這些隱藏變數會從表單內容中指派值。

再次儲存命令檔。
按一下 (驗證與部署)。輸入 RTP 值以進行驗證：

員工：Full Time Employees
實體：No Entity
期間：Jan
案例：Current
版本：BU_Version_1
年份：FY16

勾選將值套用至規則以將這些值儲存為預設值以供驗證之用，然後按一下確定。

附註：

在此步驟中，不會執行規則；不過，您必須輸入有效的成員，驗證程序才能成功。

提示時，按一下確定，然後關閉 Calculation Manager。

建立 Planning 動作功能表以執行 Groovy 指令碼

在此區段中，您會建立一個名為「管理員工」的動作功能表，其中包含執行 Groovy 指令碼的滑鼠右鍵動作功能表項目。

從左上方按一下導覽器，然後瀏覽至動作功能表 (位於「建立與管理」底下)，然後建立名為管理員工的動作功能表。

編輯「管理員工」動作功能表，並新增名為更新員工地址的子功能表項目。輸入或選取下列選項以定義功能表項目：

選項欄位	要輸入或選取的值
功能表項目	更新員工地址
標籤	更新員工地址
Type	Business Rule - 商業規則
必要的參數	員工
多維資料庫	Plan2
Business Rule - 商業規則	Groovy 新增或更新員工地址