RestAPI設定

# FastWeb RestAPI設定

適用平臺：WEB(桌面)，APP(移動端)

# 1. 簡介

RestAPI是顯示于FastWeb左側的功能表欄位，可通過云服務工具-RestAPI設定進行介面名稱的定義以及開發操作。

# 2. 設定介面

在RestAPI設定的界面，可檢視已經建立的介面的相關資訊，可在表頭的篩選編輯框中輸入資訊快速查詢所需的介面資訊。

# 2.1. 操作說明

新增介面

在RestAPI設定中，點選[新增]按鈕打開新增視窗。設定介面的資訊。設定完成後，點選[儲存]按鈕。需要注意的是，其中的選項公開介面(免驗證令牌)是為免去token認證使用的，當此項被設定為True時，原先設定的許可權路徑將失效，不再納入許可權管理的範圍。通常在使用webhook的情況下會使用到。

修改介面

如需要修改已有的介面的基礎資訊，選擇要修改的介面項，點選[修改]按鈕，打開修改介面的對話方塊，修改介面的相關資訊，修改完成後，點選[儲存]按鈕儲存介面。

刪除介面

如需要刪除介面資訊，選擇要刪除的介面項，點選[刪除]按鈕，彈出以下提示對話方塊，點選[是]將刪除已選擇的介面。如不需要刪除介面，點選[否]按鈕退出。

介面開發

如需要定義介面的詳細資訊，選擇要定義的介面名稱項，點選[介面設計]按鈕，打開介面開發視窗。介面開發視窗中預設的資訊顯示如下:

//****************說明*************************************************************/
//*  1.ToKenPerms >> 令牌許可權列表                                                 */
//*  2.URLParams  >> URL參數                                                      */
//*  3.UserInfos  >> 令牌使用者資訊                                                 */
//*  4.PostStream >> 推送流                                                       */
//*  5.GetNodeDataLink(Const ANodeName:String):TFDConnection >> 獲取節點資料庫連線*/
//*********************************************************************************/
//* "RestAPI" is a fixed name and cannot be modified */
function RestAPI()
{

}

1
2
3
4
5
6
7
8
9
10
11
12

在其中可輸入自定義的指令碼執行介面開發的相關操作。

# 2.2. 介面開發示例

接下來，我們將介紹如何在FastWeb中建立一個RestAPI。當訪問該介面的URL時，返回含有HelloWorld的json字串。

使用管理員使用者登錄FastWeb的專用管理員界面，建立介面許可權。點選[云服務工具]-[RestAPI許可權]，打開介面許可權界面，在該界面中點選[新增]按鈕，新增一個許可權節點，許可權名稱設定為HelloWorld。

建立介面。點選[云服務工具]-[RestAPI設定]，打開介面開發列表，在該界面中點選[新增]按鈕，新增一個介面，名稱設定為HelloWorld（該名稱將會作為介面呼叫時使用的名稱，建議使用英文）。其許可權路徑設定為剛才建立的介面許可權路徑，可為其指定開發的使用者。

介面開發。選擇Helloworld介面，點選[介面設計]進入到介面開發的界面。其中的主函式就是RestAPI，其輸出的結果作為介面呼叫的返回值。在RestAPI函式中輸入的內容範例如下：

//JScript
function RestAPI()
{
  return("{\"result\": \"HelloWorld\"}");
}

1
2
3
4
5

//PasScript
Function RestAPI:String;
Begin
Result := '{"result": "HelloWorld"}';
End;

1
2
3
4
5

// Make sure to add code blocks to your code group

設定角色許可權。此處我們需要設定admin使用者擁有該介面許可權，admin使用者位於系統管理員角色組中。點選[系統管理]-[角色]，打開角色頁面，點選[上頁]、[下頁]按鈕切換至系統管理員角色，點選上方的[修改]按鈕進入到許可權編輯模式，找到位於API Root中的HelloWorld，勾選，點選[儲存]完成許可權設定。這樣admin就擁有許可權呼叫該介面。

測試介面。可以使用瀏覽器或者介面測試的工具（比如Postman）開始進行測試。

獲取Token。Token是許可權令牌，根據呼叫時使用的使用者名稱與密碼產生，用於呼叫介面鑒權。其URL組成形式如下：

http://url.host?restapi=gettoken&username=admin&password=TVRJek5EVTJSR1ZzY0docA

一般的返回形式如下：

{"token":"498383E183EA689F02BEC06097D99AB7F3DBCA870CB06245DA11ACC96A22D4A3A83A315894EBE88E163F46FA62C04EE81ED7CA04FD19215C6B754FCD75414B90A836828BE47FB5B739F5B0E859C2D53B7B12330C1610738D","timedout":0,"effectivetime":44078.4733080093}

呼叫介面。其URL組成形式如下：

http://url.host?restapi=script&token=498383E183EA689F02BEC06097D99AB7F3DBCA870CB06245DA11ACC96A22D4A3A83A315894EBE88E163F46FA62C04EE81ED7CA04FD19215C6B754FCD75414B90A836828BE47FB5B739F5B0E859C2D53B7B12330C1610738D&apiname=Helloworld

測試成功的返回形式如下：

{"result": "HelloWorld"}

至此第一個RestAPI設計完成。

# 2.3. API呼叫說明

FastWeb中主要包含兩個API，分別用於獲取Token與執行指令碼。

# 2.3.1. gettoken

該方法用於獲取指定使用者的令牌，在執行指令碼時使用該令牌進行鑒權操作。

請求格式

GET
http://url.host?restapi=gettoken&username=<UserName>&password=<Password>

1
2

參數名稱	型別	描述
restapi	String	執行的`restapi`名稱，目前支援`gettoken`、`script`、`getframemaps`三種預設API，自定義的API名稱不能與這三者重複
username	String	登錄的使用者名稱稱
password	String	登錄的使用者密碼，此密碼為加密後的密碼。可在登錄後點擊右上角的使用者圖示檢視 `Password` 處第一個等號與倒數兩個等號之間的數值為加密後的密碼文字

請求示例

http://localhost:8888?restapi=gettoken&username=admin&password=TVRJek5EVTJSR1ZzY0docA

成功示例

{"token":"D5B441977EC34062EDBC6B0B079664263A1F9A421D2F004C9D0CA0500AFBB1C0A83A315894EBE88E163F46FA62C04EE81ED7CA04FD19215C6B754FCD75414B90A836828BE47FB5B7DFCA0F2831450BDDFEA4181DDF39A247","timedout":0,"effectivetime":44078.5197044329}

參數名稱	型別	描述
restapi	String	執行的`restapi`名稱，目前支援`gettoken`、`script`、`getframemaps`、`uploadfiles`四種預設API，自定義的API名稱不能與這三者重複
token	String	令牌內容
timedout	Int	超時時間，0表示在FastWeb設定的有效期內長時有效
effectivetime	Float	生效時間

失敗示例

{"token":null}

出現以上情況，請檢查登錄的使用者名稱與密碼是否填寫正確。

# 2.3.2. script

該方法用於呼叫介面指令碼。

請求格式

GET/POST
http://url.host?restapi=script&token=<token>&apiname=<ApiName>&key1=<Key1>...

1
2

也可簡化寫作下述方式：

GET/POST
http://url.host?restapi=<ApiName>&token=<token>&key1=<Key1>...

1
2

參數名稱	型別	描述
restapi	String	執行的`restapi`名稱，目前支援`gettoken`、`script`、`getframemaps`、`uploadfiles`四種預設API，自定義的API名稱不能與這三者重複
token	String	令牌內容
apiname	String	執行的介面名稱

apiname之後的參數可根據需求自行增加以及命名，FastWeb不做限制。

請求示例

http://localhost:8888?restapi=script&token=555749A7F9894B5591F709FECFB3DE43C85E4AA5E7E616E73B8FDD9367E61AA4C1365967312416B7F7B6D8593CBB88C4A3D5BFD684464CBD43FCA27342296C87&apiname=Post_Data&apikey=99&value=88

以上使用具體的API的參數也可以寫作下述方式

http://localhost:8888?restapi=Post_Data&token=555749A7F9894B5591F709FECFB3DE43C85E4AA5E7E616E73B8FDD9367E61AA4C1365967312416B7F7B6D8593CBB88C4A3D5BFD684464CBD43FCA27342296C87&apikey=99&value=88

成功示例

該成功示例需由開發人員自行開發，此處不作展示。

失敗示例

{"result":"no","msg":"無效的令牌"}

該種情況通常為令牌過期或者令牌失效，請使用gettoken重新獲取令牌。

{"result":"no","msg":"介面'ApiName'不存在"}

該種情況為介面名稱錯誤，請檢查介面名稱是否正確。

# 2.3.3. uploadfiles

該方法用於批次上傳檔案至指定的目錄。

請求格式

POST
http://url.host?restapi=uploadfiles

1
2

參數名稱	型別	描述
restapi	String	執行的`restapi`名稱，目前支援`gettoken`、`script`、`getframemaps`、`uploadfiles`四種預設API，自定義的API名稱不能與這三者重複

請求上傳的檔案與欄位資訊置於請求體中，以multipart/form-data的格式進行編組。參數說明如下：

參數名稱	型別	描述
filePath	Text	上傳的檔案路徑，在上傳前需確認FastWeb下已存在這個目錄
fileName	File	要上傳的檔案，檔案型別的參數名稱可以自行定義，但需確保參數型別為檔案型別

請求示例

http://localhost:8888?restapi=uploadfiles

以multipart/form-data的格式進行編組的參數示例如下：

參數名稱	型別	示例
filePath	Text	uploadfolder
fileName1	File	011002301211-80834085.pdf
fileName2	File	031002300311-1133672.pdf

成功示例

{
	"status": "ok",
	"message": [
		{
			"file": "uploadfolder/011002301211-80834085.pdf"
		},
		{
			"file": "uploadfolder/031002300311-1133672.pdf"
		}
	],
	"time": "2024-03-23 13:52:49"
}

1
2
3
4
5
6
7
8
9
10
11
12

# 3. 程式用法

# 3.1. 參數獲取

FastWeb的RestAPI開發模式下包含URLParams對象，該對像儲存了接收到的請求使用的參數，按照請求參數的排序產生對應的陣列。也可以直接引用參數的名稱獲取對應參數的取值。

//JScript
//獲取的參數在URLParams中，以index方式獲取，從0開始
String = URLParams.ValueFromIndex[i];

//以參數名為依據獲取
String = URLParams.Values["ParamsName"];

1
2
3
4
5
6

//PasScript
//獲取的參數在URLParams中，以index方式獲取，從0開始
String := URLParams.ValueFromIndex[i];

//以參數名為依據獲取
String := URLParams.Values['ParamsName'];

1
2
3
4
5
6

// Make sure to add code blocks to your code group

# 3.2. 預設參數值

如果想為 URLParams 設定預設值，在需要修改時再從參數中重新賦值，可使用 APIParams 來進行設定。APIParams 需在介面測試界面中進行設定，通過新增行對預設的 APIParams 進行設定。

以下給出設定預設參數值的示例部分程式程式碼，在URL參數中未指定參數值時，使用預設的參數值，如指定了參數值，則使用新的參數值。

//JScript
  var pdf="";
  var p1 = iif (URLParams.Values["Param1"] == "",APIParams.Values["Param1"],URLParams.Values["Param1"]);          //參數1
  var p2 = iif (URLParams.Values["Param2"] == "",APIParams.Values["Param2"],URLParams.Values["Param2"]);         //參數2
  var p3 = iif (URLParams.Values["Param3"] == "",APIParams.Values["Param3"],URLParams.Values["Param3"]);        //參數3
  pdf = GetPublicReportPdfUrl("report_quickstart",p1,p2,p3);  //獲取報表中心的內容，轉化為PDF 鏈接

1
2
3
4
5
6

//PasScript
  pdf := '';
  p1 := iif (URLParams.Values['Param1'] = '',APIParams.Values['Param1'],URLParams.Values['Param1']);          //參數1
  p2 := iif (URLParams.Values['Param2'] = '',APIParams.Values['Param2'],URLParams.Values['Param2']);         //參數2
  p3 := iif (URLParams.Values['Param3'] = '',APIParams.Values['Param3'],URLParams.Values['Param3']);        //參數3
  pdf := GetPublicReportPdfUrl('report_quickstart',p1,p2,p3);  //獲取報表中心的內容，轉化為PDF 鏈接

1
2
3
4
5
6

// Make sure to add code blocks to your code group

# 3.3. 流獲取

當使用Post方法進行RestAPI呼叫時，獲取到的Body流資訊會儲存在PostStream中，比如一些JSON資訊，供函式處理呼叫。以下是將流中的數據轉換為文字的方法，轉換后的文字在 s 變數中，可供處理使用。

//JScript
function RestAPI()
{
    var Stream,s;
    Stream = new TStringStream("",UTF8Encoding);
    try{
        Stream.LoadFromStream(PostStream);
        s = Stream.DataString;
        Result = s;
    }
    finally{
        Stream.Free;
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14

//PasScript
Function RestAPI:String;
var
  Stream: TStringStream;
  s: String;
begin
  Stream := TStringStream.Create('',UTF8Encoding);
  try
    Stream.LoadFromStream(PostStream);
    s := Stream.DataString;
    String := PostStream.Text;
    Result = s;
  finally
    Stream.Free;
  end;
end;

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

// Make sure to add code blocks to your code group

# 3.4. 呼叫節點資料庫(DB)

在FastWeb的RestAPI開發模式下可以呼叫節點資料庫連線。呼叫的方法可參考下面的示例。如果需要了解如何建立所需的節點資料庫請查閱節點資料庫(DB)。

//JScript
function RestAPI()
{
  var D,Q,S;
  D = GetNodeDataLink("Cloud");//Cloud為節點資料庫中設定的連線，此處可直接進行呼叫
  Q = new TFDQuery(Nil);
  Try{
    q.Connection = D;
    q.SQL.Text = " select * from Equipment";
    q.Open;
    ...
  }
  Finally{
    q.Free;
    d.Free;
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

//PasScript
Function RestAPI:String;
Var
  D:TFDConnection;
  Q:TFDQuery;
  S:String;
Begin
  D:=GetNodeDataLink('Cloud');//Cloud為節點資料庫中設定的連線，此處可直接進行呼叫
  Q:=TFDQuery.Create(Nil);
  Try
    q.Connection := D;
    q.SQL.Text := ' select * from Equipment';
    q.Open;
    ...
  Finally
    q.Free;
    d.Free;
  End;
End;

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

// Make sure to add code blocks to your code group

← SVG編輯器 RestAPI許可權→