跳至主要內容

WebAPI

概述

VDN 提供了 WebAPI 网络应用接口，通过该接口外部应用可以很便捷的访问服务端的 WebAPI(PB 插件)，支持 HttpClient、Ajax、WebSocket 以 Get\Post 的方式进行访问交互，实现跨应用、跨语言、跨平台的功能扩展。

充分利用了 VDN 的高并发及 PB 的便捷开发,最大程度的复用 PB 代码。大数据压缩返回，提高数据传输速度。

提示

WebAPI 访问主要通过两种方式

1、内置 API 接口 通过内置的 API 访问路径访问，接口协议参照 JSON-RPC 协议,是一种轻量级的远程调用协议,简单、小巧、灵活;详见【协议描述】。

访问格式举例:

http://www.xxxx.net:8088/api?method=[PBPlugin].nvo_obj.f_good&params=a1/a2&format=json

2、URL 访问 使用项目发布--扩展属性里设置的 URL 子路径访问，返回的数据格式可以自由定义;详见【URL 访问】

一、安全保障

VDN 为 WebAPI 提供了多重安全保障:

  • 访问级别

由提供服务的 PB 插件决定了访问级别，针对 WebAPI 分为【匿名访问】、【用户验证】、【令牌访问】这几种安全级别

【匿名访问】对外部访问不设置限制，可以任意访问

【用户验证】WebAPI 通过guo_vdn.wa_setLogin(...)函数设置用户已登录后才可以进行访问。登录函数须以_nv作为后缀以绕过验证，详见【函数后缀】

【令牌访问】必须通过约定的规则获取令牌后才可以进行访问, 适用于外部域进行访问,安全性高,详见：如何获取令牌

  • 来源验证

通过设置【验证来源】选项，VDN 会对外部访问的来源都进行验证，只有属于预先设定的来源路径才可以访问，杜绝非法的访问。来源设定详见：外部来源

  • 自定义验证

用户可以在插件代码中增加自定义验证，设定握手协议，只有满足条件的调用才给予正确的返回值.

二、WebAPI 设置

【系统设置】-【Web】-【Web 设置】-【WebAPI】关于 WebAPI 的选项

API 页面:定义访问 WebAPI 的文件名,一个 URL 子路径,默认 api.可以定义为任意不重复的英文名称,例如定义为 abc,则访问 API 的 URL 路径就为:http://www.xxx.com:8088/abc

跨域访问:是否允许外部站点、程序跨域访问 WebAPI,如果不选择则只允许本站点的页面访问 WebAPI，外部将无法访问。

验证来源:当访问来源为外部时，判断来源地址是否属于在【外部来源】中设置的地址列表，如果不属于则拒绝访问。

三、协议描述

VDN 的 WebAPI 传输协议基于 JSON-RPC 协议格式进行了扩展，主体完全相同.

Get 方式格式示例
//浏览器直接输入或者httpClient以get方式访问
"http://www.xxxx.net:8088/api?method=\[PBPlugin\].nvo_obj.f_good&params=a1/a2&format=json"
//或者
Ajax Get:
{
    "method": "nvo_bill.getoper_json",
    "params": "a1/a2",
    "id":"GetData"  //可省略
}
Post 方式格式示例
//JSON 格式: 
{
   "method": "[PBPlugin].f_getdata",
  "params": [ "a1", "a2" ],
   "id": "GetData" //可省略
 }

3.1、参数

在 JSON 中是不区分大小写的，但在 URL 中必须都为小写，所以统一定为小写.格式:

id

  • 类型: string
  • 可选

调用标识符(非必须) 任意值,调用后会原值返回，适用于一些异步操作等情况

method

  • 类型: string
  • 必须

调用的函数名

调用对象的函数

[ProjectName].ClassName.Function

调用全局函数

[ProjectName].Function

注意项目名称必须以方括号括起来,不区分大小写

示例
[pbplugin].nvo_obj.f_goods

[pbplugin].f_getdata

params

  • 类型: string
  • 可选

参数列表

Post JSON 格式

["parm1","parm2"...]

Get URL 格式

parm1/parm2

当以 Get 方式以 URL 格式传递时使用/分割，参数中有/时，使用转义字符^/ 转义,推荐使用 URLEncode 进行编码

示例
JSON: "params":["a1","a2"]

URL: parms=a1/a2

format

  • 类型: string
  • 可选

当以GET 方式访问时告知服务端以什么格式返回数据

  • text   (默认)以文本格式返回

  • json   以 json 格式返回

示例
format=json

3.2、返回参数

返回格式可以为 JSON 或文本格式，由访问时要求的格式(Accept)决定.

文本格式则是直接返回函数的字符串返回值，error 开头则为发生错误.

JSON 格式参数如下:

ID

调用标识符 调用时传入的参数原样返回

Error

调用时发生的错误，没有错误则返回 null

{
//一个数字，表示发生错误的类型
Code int
//提供简短错误描述的字符串。
Message string
//原始类型或结构化类型值，包含了关于错误的附加信息。**这个成员可以省略**。
//该成员的值由服务器端定义（如：详细的错误信息，嵌套的错误信息等）。
Data string
}

Result

调用函数的返回值。发生错误返回 null

字符串值或者 JSON 对象

JSON 格式
{
  "ID": "123456",
  "Error": null,
  "Result": "函数返回值"
}

关于 Result 值为 JSON 对象或者文本格式的区别：

默认情况 Result 都是返回字符串值的，但当调用的函数是以_json(例如:f_getdata_json)结尾时，函数的返回值将以 JSON 对象作为 Result 的子节点返回

举例：函数 f_getdata 和 f_getdata_json 的代码完全相同，都是返回字符串 {"data":\["abc","123"\]}时

f_getdata 返回 JSON 格式
//Result 的值为字符串类型
{
  "ID":"123456",
  "Error":null,
  "Result":"{\"data\": [\"abc\",\"123\"]}"
}
f_getdata_json 返回 JSON 格式
//Result 的值为 JSON 对象，可以通过 Result.data 直接访问该对象
{
  "ID":"123456",
  "Error":null,
  "Result": {"data":["abc","123"]}
}

这个在示例里有详细的比对

四、Method 后缀

为了方便对函数特征进行标注，VDN 为 Method 定义几种后缀方便操作,后缀可以位于对象名或者函数名中，以下划线开头

例如：

nvo_obj.getData_wc 代表该函数参数和返回值均为 Blob,传递 Unicode 字符

nvo_obj_wc.getData 代表该对象的所有函数参数和返回值均为 Blob,传递 Unicode 字符

可以跟多个后缀，例如：nvo_obj.getData_wc_json

参数说明适用
_nv类名或者函数名以_nv 结尾则不需要验证登录,即便是该项目是用户登录验证模式WebAPI
_json类名或函数名以_json 结尾，则其输出的内容作为返回 JSON 的一部分，否则以字符串形式赋值给 Result。(URL 子路径访问时改后缀无用)WebAPI/WebApp
_ext类名或者函数名以_ext 结尾则表示 WebApp 的后台 PBD 函数可以以 WebApi 的形式被外部调用,默认情况下处于安全考虑 WebApp 的后台函数是不允许被外部调用的WebApp
_wc类名或函数名以_wc(wide character)结尾,则函数参数和返回值均为 Blob,便于接收和返回 Unicode 字符集
注：Unicode 字符到达 VDN 后将被转换为 UTF8 返回给前台
V2019.1.1.3 之后版本支持		WebAPI/WebApp

五、全局变量

  • PB 后台不支持全局变量，要使用全局变量可以使用

guo_vdn.wa_SetGloal  整个服务的全局变量

guo_vdn.wa_SetSession 会话级别的全局变量

注意

共享模式虽然可以保存全局变量，但是请求每次进入的共享会话不会是同一个，所以这个全局变量仅限于保存一些针对会话的标志性变量，比如记录当前会话的 SQLCA 是否已经连接

  • 系统本身有两个内置的全局变量

    • nuo_vdncore guo_vdn 用来操作 Web 变量,提供 httpClient 等相关的功能，只需要定义，服务会自动进行实例化和初始化

    • string __LastError 用来记录函数执行过程中的错误，只要改变量有值，服务就会直接返回标注的错误内容

相关信息

共享模式下，当__LastError 包含 ERROR-EXIT 字符串时，服务将会停止当前的共享会话，重新启用新的会话

所有模式下，当__LastError 包含 ERROR-HALT 字符串时,服务将会停止当前的应用程序池，重新启用新的应用程序池

六、数据压缩

当返回数据的体积达到设定值（Web 设置--内容压缩）时，将以 GZip 压缩返回。

由访问时的 Header 值 Accept-Encoding 指定是否支持 gzip 来决定。大多数浏览器或 Ajax 组件都默认支持该选项，不需要手动设定，也不需要手动解压。

如果使用后台编写代码访问，则根据情况进行代码处理.

七、URL 访问

7.1、子路径

V2020.1.1.1 版本之后 WebAPI 支持直接 URL 路径访问，这样在提供给第三方接口是可以有更好的语义，使用起来更方便。

项目发布时在 项目发布--扩展属性--URL 子路径 处设置子路径

第三方调用可以直接通过 URL 地址对应的 API 函数，URL 结构为：

http://www.xxx.com:port/URL子路径/object/function?params=p1/p2
//或者
http://www.xxx.com:port/URL子路径/function?params=p1/p2

其中 params 为可选参数，使用/分割，参数中有/时，使用转义字符^/ 转义,推荐使用 URLEncode 进行编码

  • 访问示例一

项目 URL 子路径为 secure``,项目中的对象为 common,要调用的项目函数为 gettoken,要传入的参数为 abc`

http://www.xxx.net:8088/secure/common/gettoken?params=abc
  • 访问示例二

项目 URL 子路径为 secure``,函数为 gettoken,要传入的参数为 `abc

http://www.xxx.net:8088/secure/gettoken?params=abc
//当不需要传入参数时为：
http://www.xxx.net:8088/secure/gettoken

7.2、body

当使用 POST 给函数传递主体数据时，可以通过 guo_vdn.wa_getBody()来获取主体的内容

返回的内容可通过 guo_vdn.wa_setHeader("Content-Type",类型)来设置

示例
guo_vdn.wa_setHeader("Content-Type","application/json")
//或
guo_vdn.wa_setHeader("Content-Type","text/xml")

如果不进行这个设置，VDN 将自动根据请求的 Accept 类型来自动设置

7.3、发生错误

当设置了__LastError 错误内容，接口将会设置 返回 500 错误 (ResponseCode)，__LastError 的内容依然会被写入到页面中返回，前台调用可以获取页面主体显示

八、Header 参数

WebAPI 会以下 Header 参数会进行解析，针对不同的参数值产生不同的效果

Content-Type

告知服务器传入的数据的格式为 json,在 Post 方式时需要指明。

前台代码
Post: contentType: "application/json";

Accept

application/json告知服务器端以 json 格式返回数据，否则以文本方式返回

前台代码
Post:
    dataType: 'json'
Get:
    "http://www.xxx.net?method=...&format=json"

Accept-Encoding

当值包含 gzip 时，数据达到设定值则会压缩返回。大部分浏览器默认为[gzip, deflate]

九、示例解析

示例代码

前台示例代码位置：Example\Web功能\WebAPI\ 目录下

PB 插件代码位置：Example\PB插件示例 目录下

示例代码主要使用了 JQuery 的 ajax 对象进行了访问演示，JSON 解析为 Table 表格使用了 jquery.jsontotable.min 插件，均为演示需要，实际使用可以任意不受限制。

Get 方式访问

URL 参数:

  • method=[PBPlugin].nvo_obj.f_good  执行项目名称为 PBPlugin(不区分大小写)中对象名为 nvo_obj 的 f_goods 函数

  • params=a1/a2  传入 a1、a2 两个字符串参数给函数

  • format=json  通知服务器返回格式为 json,如果不带 format 参数则默认返回字符串格式,也可以通过下面的 dataType: 'json'设定返回值为 json.

Post 方式访问

先使用一个对象设定参数值，然后通过 JSON.stringify 序列化为 JSON 字符串

序列化后的 JSON 格式
{
  "id": "GetData",
  "method": "[PBPlugin].f_getdata",
  "params": ["a1", "a2"]
}

  • id: 任意字符，传入什么值，服务器就返回什么值，可以为空或者不输入

  • method:"[PBPlugin].f_getdata" 调用项目 PBPlugin 的 f_getdata 函数

  • params:传入 a1、a2 两个字符串参数给函数

  • dataType:为 JQUERY 的 ajax 对象属性，指定返回格式为 json,对应 Header 值:Accept

  • contentType:为 JQUERY 的 ajax 对象属性,告知 VDN 传入的数据为 json 格式,对应 Header 值:Content-Type

浏览器 Get


http://localhost:8088/api?method=\[PBPlugin\].nvo_obj.f_good&params=a1/a2

//如果设置了子路径为 pbplugin 则可以通过 URL 直接访问

http://localhost:8088/pbplugin/nvo_obj/f_good&params=a1/a2

浏览器 Get JSON

http://localhost:8088/api?method=\[PBPlugin\].nvo_obj.f_good&params=a1/a2&format=json
Copyright© 2014-2025 烟台沃森电子软件技术有限公司