RAD Server REST API 釋出實戰

– 11 分鐘閱讀

RAD Server 簡化了 REST API 的開發與佈署流程，尤其對於 Delphi 開發者而言，更能有效整合現有資料函式庫與商業邏輯。本文從 InterBase 資料函式庫服務的啟動與 EMSDevServer 的執行開始，逐步引導讀者完成 RAD Server 的初始設定，包括例項名稱設定、預設使用者與群組建立，以及 EMS Console 的帳號密碼組態。接著，示範如何透過 RAD Server 內建資源與 EMSConsole 進行基本操作和資源管理，並詳細說明如何建立自訂 REST API 資源，包含 Delphi 套件專案的建立、資源類別的實作、套件檔案的編譯與佈署，以及伺服器端的重新載入。文章也提供了程式碼範例，展示如何利用 RAD Server 的資料函式庫操作自動對映功能，實作與 Web Broker 架構類別似的 REST API 釋出效果，並透過 IToDoData 介面暴露相同功能。

RAD Server 設定與 REST API 釋出

環境準備與初始設定

首先，請確保系統中已安裝並執行 InterBase 資料函式庫服務。透過 Windows 開始功能表搜尋並執行 InterBase Server Manager，如圖 13.1 所示。若服務未啟動，請手動啟動。預設安裝情況下，InterBase 例項名稱為 gds_db，此名稱將於後續 RAD Server 設定中使用。

接著，開啟 Windows 命令列介面並輸入 EMSDevServer 命令以啟動 RAD Server。Delphi 安裝過程中已將 bin 目錄加入系統路徑，因此可直接執行。

重要提示：許多地方仍使用 EMS（Enterprise Mobility Services）指稱 RAD Server，這是其舊稱。

RAD Server 安裝精靈與初始組態

首次執行 EMSDevServer 或使用 -setup 引數時，將顯示安裝精靈（見圖 13.2）。該精靈用於建立 RAD Server 系統資料函式庫及組態 ini 檔案，並可選擇性建立預設使用者與群組。

  1. 在精靈首頁輸入 InterBase 伺服器例項名稱（預設為 gds_db）。
  2. 第二步驟保留預設選項以建立範例使用者與群組。
  3. 設定 EMS Console 的存取帳號（預設為 consoleuser）與密碼（預設為 consolepass）。
  4. 最後，檢視設定摘要並點選 Finish 完成設定。

完成後，EMS Development Server 控制檯將顯示日誌視窗（見圖 13.4），其中記錄了組態檔案載入、資料函式庫連線及可用資源端點等資訊。

RAD Server 基本操作與資源管理

點選 Open Browser 按鈕可透過預設瀏覽器存取內建的 /version 資源（見圖 13.5）。所有請求均會被記錄於控制檯日誌中。

此外，可透過 Open Console 按鈕啟動 EMSConsole 應用程式以管理使用者、群組及檢視 REST API 分析資料。預設情況下，EMS Server 使用 HTTP 連線埠 8080，而 EMS Console 使用 8081。

建立自訂 RAD Server 資源

RAD Server 的架構設計允許透過 Delphi 套件（package）檔案新增自訂 REST API 資源。這些套件會在伺服器啟動時被載入，而相關路徑則記錄於 ini 組態檔案中。

本章節將展示如何利用 RAD Server 的強大功能實作資料函式庫操作的自動對映，並進一步透過 IToDoData 介面暴露相同功能，從而實作與前一章 Web Broker 架構類別似的 REST API 釋出效果。

RAD Server 資源開發流程

  1. 建立新的 Delphi 套件專案。
  2. 實作自訂的 REST API 資源類別。
  3. 編譯產生套件檔案（.bpl）。
  4. 將產生的套件檔案放置於 RAD Server 組態的套件目錄。
  5. 重啟 RAD Server 以載入新的資源。

範例程式碼：自訂資源實作

unit ToDoResource;

interface

uses
  System.SysUtils, System.Classes, EMS.Resource, EMS.ResourceAPI;

type
  [ResourceName('ToDo')]
  TToDoResource = class(TDataModule)
  published
    procedure Get(const AContext: TEndpointContext; const ARequest: TEndpointRequest; const AResponse: TEndpointResponse);
  end;

implementation

procedure TToDoResource.Get(const AContext: TEndpointContext; const ARequest: TEndpointRequest; const AResponse: TEndpointResponse);
begin
  // 處理 GET 請求的邏輯
end;

end.

#### 內容解密：

此段程式碼定義了一個名為 TToDoResource 的資源類別，用於處理對 /ToDo 端點的請求。其中：

  • ResourceName 屬性指定了資源名稱。
  • Get 方法處理 HTTP GET 請求。
  • AContext、ARequest 和 AResponse 分別代表端點上下文、請求物件和回應物件，用於存取請求引數和發送回應。

圖表說明：RAD Server 架構概覽

圖表翻譯： 此圖展示了 RAD Server 的基本架構：

  • 使用者端透過 HTTP 請求與 RAD Server 互動。
  • RAD Server 連線 EMS Console 以進行管理操作。
  • 自訂資源（Custom Resources）被載入至 RAD Server。
  • 自訂資源可進一步與資料函式庫操作進行互動。

使用RAD Server建立REST API資源

在Delphi中開發RAD Server資源是建立REST API服務的關鍵步驟。本章節將詳細介紹如何使用RAD Server Wizard建立資源，並將資料函式庫操作對映為HTTP端點。

建立RAD Server資源套件

首先，從Delphi的File選單開啟New Items對話方塊，選擇RAD Server類別下的RAD Server Package圖示，如圖13.7所示。

圖13.7：New Items對話方塊中的RAD Server Package精靈

在精靈的第一頁，您可以選擇建立空的套件或包含資源的套件。通常選擇第二個選項來建立帶有資源的套件。

設定資源名稱和基礎類別

在精靈的第二頁，需要指定資源名稱和實作資源的基礎類別。資源名稱將與URL對應。如果計劃在資源中加入元件，建議選擇Data Module；否則，可以選擇Plain Unit。對於第一個範例，輸入名稱如tododatabase，並選擇Data Module。

定義端點

在精靈的第三頁（如圖13.8所示），您可以指定要加入到資源的端點。這些端點將轉換為不同的HTTP請求型別和URL。可以手動定義端點，或選擇使用資料函式庫端點。

圖13.8：RAD Server Package精靈的端點定義頁面

對於第一個範例，選擇資料函式庫端點選項。接著，在第四頁選擇預設的SQLite連線，並挑選一個可用的資料表。

完成精靈並檢查產生的資料模組

完成精靈後，檢查產生的資料模組。進行以下變更：

  1. 開啟FDConnection1元件的連線編輯器，將Database值設為與之前章節相同的路徑，例如C:\Users\Public\Documents\ToDos.db。
  2. 將TFDQuery元件重新命名為qryTodo。
  3. 修改SQL屬性的第一行以選取ToDos表中的所有記錄。
  4. 將TEMSDataSetResource元件重新命名為dsrTodo。

程式碼範例：資料模組定義

type
  [ResourceName('tododatabase')]
  TTododatabaseResource1 = class(TDataModule)
    FDConnection1: TFDConnection;
    qryTodo: TFDQuery;
    [ResourceSuffix('Todo')]
    dsrTodo: TEMSDataSetResource;
  published
  end;

#### 內容解密：

此段程式碼定義了一個名為tododatabase的資源，並將其對映到特定的URL。TTododatabaseResource1類別包含資料函式庫連線、查詢和資料集資源元件。[ResourceSuffix('Todo')]屬性指定了URL的子路徑。

執行與測試

編譯並執行應用程式。由於這是一個套件專案，它將由RAD Server作為主機應用程式載入。檢查RAD Server日誌以確認資源已正確註冊。

日誌範例：

"RegResource": {
  "name": "tododatabase",
  "endpoints": [
    {
      "name": "dsrTodo.List",
      "method": "Get",
      "path": "tododatabase/Todo/",
      "produce": "application/json, *;q=0.9"
    },
    {
      "name": "dsrTodo.Get",
      "method": "Get",
      "path": "tododatabase/Todo/{id}",
      "produce": "application/json, *;q=0.9"
    }
  ]
}

#### 內容解密：

此日誌顯示了tododatabase資源已註冊，並列出了可用的端點，包括用於列出和檢索特定記錄的GET請求。

建立ToDo列表伺服器

現在，建立一個根據前幾章架構的ToDo列表伺服器，而不是直接暴露資料函式庫。這需要建立新的RAD Server資源，並手動定義端點。

  1. 建立新的資料夾結構，包括resource、client和shared子資料夾。
  2. 再次執行RAD Server精靈，這次選擇Plain Unit，並命名資源為todo。
  3. 在第三頁選擇Sample EndPoints，並勾選所有五個子元素，以暴露CRUDL操作。
  4. 儲存產生的套件專案和單元檔案。

此圖示說明瞭專案結構和RAD Server精靈的使用流程

**圖表翻譯：**此圖展示了使用RAD Server精靈建立新資源的步驟，從開始到儲存專案檔案的流程。

#### 圖表說明：

此Plantuml圖表呈現了建立ToDo列表伺服器資源的主要步驟，包括執行精靈、選擇資源型別、命名資源、定義端點和儲存專案。透過此圖，可以清楚瞭解建立資源的流程和相關決策點。

使用RAD Server實作ToDo列表REST API

RAD Server中的ToDo列表資源實作

在RAD Server中實作ToDo列表資源需要經過多個步驟，包括設定專案、複製必要的單元和檔案、以及實作資源類別的方法。

步驟1：設定RAD Server專案

  1. 複製必要單元和檔案：將uToDoTypes.pas和uToDoUtils.pas單元從之前的ToDoListWebBroker專案複製到共用目錄，並將它們新增到套件專案中。同時，將uDMToDo.pas和uDMToDo.dfm檔案複製到資源目錄。
  2. 設定專案選項：在專案選項中，將共用資料夾新增到Delphi編譯器的搜尋路徑中。

步驟2：實作TToDoResource類別

  1. 開啟uToDoRes單元：在程式碼編輯器中開啟由精靈產生的uToDoRes單元。
  2. 新增必要單元：在介面區段的uses子句中新增uToDoTypes單元，在實作區段的uses子句中新增uToDoUtils和uDMToDo單元。
  3. 宣告私有欄位和方法：在TToDoResource類別中宣告一個名為FToDoData的私有欄位，型別為IToDoData。同時，宣告一個名為GetToDoData的方法，傳回相同的介面。

實作資源方法

Get方法

procedure TToDoResource.Get(
  const AContext: TEndpointContext;
  const ARequest: TEndpointRequest;
  const AResponse: TEndpointResponse);
begin
  var AToDos := TToDos.Create;
  try
    GetToDoData.ToDoList(AToDos);
    var RespStr := ToDosToStr(AToDos);
    AResponse.Body.JSONWriter.WriteRaw(RespStr);
  finally
    AToDos.Free;
  end;
end;

內容解密：

  • 建立一個TToDos物件來儲存ToDo記錄列表。
  • 呼叫GetToDoData.ToDoList方法從資料函式庫中檢索ToDo記錄。
  • 將檢索到的記錄轉換為JSON字串。
  • 將JSON字串寫入回應主體。

GetItem方法

procedure TToDoResource.GetItem(
  const AContext: TEndpointContext;
  const ARequest: TEndpointRequest;
  const AResponse: TEndpointResponse);
var
  AToDo: TToDo;
  RespStr: string;
begin
  var Id := ARequest.Params.Values['item'].ToInteger;
  if GetToDoData.ToDoRead(Id, AToDo) then
    RespStr := ToDoToStr(AToDo)
  else
    RespStr := 'Failed';
  AResponse.Body.JSONWriter.WriteRaw(RespStr);
end;

內容解密：

  • 從請求引數中取得要檢索的ToDo專案的ID。
  • 呼叫GetToDoData.ToDoRead方法讀取指定的ToDo記錄。
  • 將讀取到的記錄轉換為JSON字串。
  • 將JSON字串寫入回應主體。

建立RAD Server客戶端應用程式

步驟1：建立新專案

  1. 建立空白多裝置專案：將專案儲存為ToDoListEMS，位於客戶端資料夾中。
  2. 新增必要單元：將uToDoTypes和uToDoUtils單元新增到專案中。

步驟2：實作資料模組

  1. 新增資料模組：將新的資料模組新增到客戶端專案，儲存為uDMToDoEMS，並將其Name屬性更改為DMToDoEMS。
  2. 實作IToDoData介面：在資料模組的公開區段中宣告五個IToDoData介面方法。

使用RAD Server建立強大的後端服務

RAD Server是Embarcadero提供的一個強大的後端服務解決方案，專為行動裝置應用程式設計。本章節將介紹如何使用RAD Server建立多層架構，並為跨平台的Delphi行動應用程式提供可重複使用的功能。

建立RAD Server客戶端應用程式

  1. 建立資料模組：首先，建立一個新的資料模組（Data Module），並在其中實作IToDoData介面。這個介面定義了與待辦事項（ToDo）相關的操作，包括建立、讀取、更新和刪除。

  2. 實作介面方法：使用TEMSProvider元件連線到RAD Server，並使用TBackendEndpoint元件來呼叫後端的REST API。為每個API端點建立對應的TBackendEndpoint元件，並設定其Resource屬性和Response屬性。

    procedure TDMToDoEMS.ToDoList(AList: TToDos);
begin
  AList.Clear;
  BeToDoList.Execute;
  StrToToDos(RrespToDo.Content, AList);
end;

function TDMToDoEMS.ToDoRead(Id: Integer; out AValue: TToDo): Boolean;
begin
  BeToDoRead.ResourceSuffix := Id.ToString;
  BeToDoRead.Execute;
  Result := RrespToDo.Content <> 'Failed';
  if Result then
    AValue := StrToToDo(RrespToDo.Content);
end;

function TDMToDoEMS.ToDoCreate(AValue: TToDo): Integer;
var
  StrStr: TStringStream;
begin
  Result := 0;
  StrStr := TStringStream.Create(ToDoToStr(AValue), TEncoding.UTF8);
  try
    BeToDoCreate.Params.Clear;
    BeToDoCreate.AddBody(StrStr, TRESTContentType.ctAPPLICATION_JSON);
    BeToDoCreate.Execute;
  finally
    StrStr.Free;
  end;
end;

function TDMToDoEMS.ToDoUpdate(AValue: TToDo): Boolean;
// 類別似ToDoCreate的實作，但使用rmPUT方法
end;

function TDMToDoEMS.ToDoDelete(Id: Integer): Boolean;
begin
  BeToDoDelete.ResourceSuffix := Id.ToString;
  BeToDoDelete.Execute;
  Result := True;
end;

程式碼解密：

  • TDMToDoEMS.ToDoList：清除待辦事項列表，執行後端查詢操作，並將結果JSON字串轉換為待辦事項列表。
  • TDMToDoEMS.ToDoRead：根據ID查詢單一待辦事項，執行後端讀取操作，並將結果轉換為待辦事項物件。
  • TDMToDoEMS.ToDoCreate：建立新的待辦事項，將待辦事項物件轉換為JSON字串並作為請求主體傳送到後端。
  • TDMToDoEMS.ToDoUpdate：更新待辦事項，類別似於建立操作，但使用PUT方法。
  • TDMToDoEMS.ToDoDelete：刪除待辦事項，根據ID執行後端刪除操作。

RAD Server的強大功能

RAD Server不僅提供了REST API發布功能，還包括使用者和群組管理、API分析以及行動推播通知等功能。這使得它成為Delphi行動應用程式後端的理想選擇。

佈署到應用程式商店

在完成應用程式的開發和測試後，下一步是將其佈署到應用程式商店。本章節還將討論如何新增美術資源、透過廣告和應用內購買實作貨幣化，以及如何自動化開發流程以提高效率。

RAD Server架構圖

@startuml
skinparam backgroundColor #FEFEFE
skinparam sequenceArrowThickness 2

title RAD Server REST API 釋出實戰

actor "客戶端" as client
participant "API Gateway" as gateway
participant "認證服務" as auth
participant "業務服務" as service
database "資料庫" as db
queue "訊息佇列" as mq

client -> gateway : HTTP 請求
gateway -> auth : 驗證 Token
auth --> gateway : 認證結果

alt 認證成功
    gateway -> service : 轉發請求
    service -> db : 查詢/更新資料
    db --> service : 回傳結果
    service -> mq : 發送事件
    service --> gateway : 回應資料
    gateway --> client : HTTP 200 OK
else 認證失敗
    gateway --> client : HTTP 401 Unauthorized
end

@enduml

圖表翻譯： 此圖示展示了RAD Server的架構，包括客戶端應用透過REST API與RAD Server互動，以及RAD Server與後端資料函式庫和其他功能的整合。

玄貓 BlackCat

玄貓 BlackCat

技術愛好者，專注於分享程式開發、雲端技術與 AI 應用的心得體會。