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权限→