准备与添加 Swagger API 数据源¶
EnOS 数字孪生可视化可通过 Swagger API 连接外部数据源数据。
准备 Swagger doc¶
本文介绍如何使用 Swagger API 对接数据至数字孪生可视化。用户需遵循 Swagger 对接规范,参见 Swagger 官方规范。
接口¶
如需数字孪生可视化获取数据并使用,则需在 Swagger doc 中使用以下接口获取数据。
Get Entity¶
请根据以下示例定义接口中的字段:
使用 key: {path}
,定义接口 path 作为唯一 key。
使用 name: paths.{path}.get.summary
,定义 summary 字段作为页面展示名称。
在 paths.{path}.get.parameters
中添加 in:"query"
,将 parameters[index].name 作为 param key 传递给接口。
使用 parameters[index].type == "内容"
,定义数据为内容。
使用 parameters[index].enum = ["选项1", "选项2"]
,定义数据为下拉选项。
使用 format == "date-time"
,定义数据为日期。
Get Fields¶
请根据以下示例定义接口中的字段:
如需解析 paths.{path}.get.responses[200].schema
字段,type 必须为 array
。
使用 paths.{path}.get.responses[200].schema.originalRef
获得 entity 的结构。
使用 definitions[originalRef].properties
结构,定义需返回的 properties。
使用 definitions[originalRef].properties[property].description
,定义 [property] 为返回数据的 key, description 为返回数据的 name(若无 description,则与 key 相同)。
Swagger doc 示例¶
{
"swagger": "2.0",
"info": {
"description": "API management platform",
"version": "1.0",
"title": "API management Restful APIs",
"termsOfService": "http://localhost:xxxx/",
"contact": {
"name": "EnOS Cloud QA team",
"email": "xxx@envision-xxxx.com"
}
},
"host": "172.16.47.25:xxxx",
"basePath": "/",
"tags": [
{
"name": "dtv",
"description": "Api Group Controller"
}
],
"paths": {
"/jarvis/group/list": {
"get": { // 数字孪生可视化只会扫描 get 请求
"tags": [
"dtv", // 对需要通过 Swagger API 对接至数字孪生可视化的数据接口,需打上 dtv 标签
],
"summary": "Summary:数字孪生可视化接口:项目列表展示",
"description": "DTV接口注释",
"operationId": "listUsingGET",
"produces": [
"*/*"
],
"parameters": [
{
"name": "projectId",
"in": "query", // 添加 `in:"query"`,将 parameters[index].name 作为 param key 传递给接口
"description": "projectId",
"required": true,
"type": "string" // 如需显示为下拉选项,需提供 enum 字段;如为日期,需设置 format 为 `date-time` 或 `date`。
}
],
"responses": { //数据接口返回数据类型 为 JSON 数组,格式如下。items 的 originalRef 指向 item 实体定义。
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": {
"originalRef": "MjolnirApiGroup",
"$ref": "#/definitions/MjolnirApiGroup"
}
}
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not Found"
}
},
"deprecated": false
}
}
},
"definitions": {
"MjolnirApiGroup": {
"type": "object",
"properties": {
"createdTime": {
"type": "string",
"format": "date"
},
"dateStringContent": {
"type": "string",
"format": "date"
},
"id": { // 对 properties 中的每个 prop 可添加 description 定义数据项的展示列名;可添加 type 定义数据类型。格式如下:
"type": "string",
"description": "项目ID"
},
"javaUtilDate": {
"type": "string",
"format": "date"
},
"javaUtilDateTime": {
"type": "string",
"format": "date-time"
},
"name": { //为返回数据的 key
"type": "string",
"description": "项目名称" //为返回数据的 name,若无 description,则 name 与 key 相同。
},
"projectId": {
"type": "string"
},
"status": {
"type": "integer",
"format": "int32"
},
"updatedTime": {
"originalRef": "Timestamp",
"$ref": "#/definitions/Timestamp"
}
},
"title": "MjolnirApiGroup"
}
}
}
校验 Swagger doc¶
你可以使用 Swagger 的 Get Data 接口来校验 Swagger doc 的配置是否有效:通过 host + swaggerPath + query parameter + fields 参数进行请求,示例如下。
http://jarvis.apaas-cn2.eniot.io//jarvis/group/list?fields=dateStringContent,id&projectId=aaa
连接至数字孪生可视化¶
通过以下步骤,添加此类外部数据源:
在左侧导航栏中,选择 指标工具 > 数据源。
选择 外部数据源 页签。
选择 新建数据源 并提供所需信息。
类型:选择
Swagger API
。名称:指定数据源的名称。
可见范围:指定数据源的范围。
内部:仅限于 OU 内部使用。
公开:可供其他 OU 使用。
Host:输入 Swagger 服务器路径。
Doc Path:输入 Swagger doc 路径。
缓存元数据:指定清空元数据缓存的时间。
缓存值数据:指定清空值数据缓存的时间。
选择 确定。
连接后,可以在 图表编辑器 中选择配置好的 Swagger API 外部数据源。
返回码¶
在组件中选择 Swagger API 数据源后,需通过查看返回码确认是否请求成功。若返回 code 为 0,则数据连接成功;若返回其他 code,则数据连接失败。
成功示例¶
{
"code": 0,
"message": "成功",
"data": exampledata
}
失败示例¶
{
"code": 500,
"message": "错误信息"
}
登录鉴权¶
Swagger API 连接数据无鉴权,如需鉴权,联系系统管理员。
相关信息¶
有关缓存的更多信息,参见 配置数据源缓存。