准备与添加 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

连接至数字孪生可视化


通过以下步骤,添加此类外部数据源:

  1. 在左侧导航栏中,选择 指标工具 > 数据源

  2. 选择 外部数据源 页签。

  3. 选择 新建数据源 并提供所需信息。

    • 类型:选择 Swagger API

    • 名称:指定数据源的名称。

    • 可见范围:指定数据源的范围。

      • 内部:仅限于 OU 内部使用。

      • 公开:可供其他 OU 使用。

    • Host:输入 Swagger 服务器路径。

    • Doc Path:输入 Swagger doc 路径。

    • 缓存元数据:指定清空元数据缓存的时间。

    • 缓存值数据:指定清空值数据缓存的时间。

  4. 选择 确定


连接后,可以在 图表编辑器 中选择配置好的 Swagger API 外部数据源。


返回码


在组件中选择 Swagger API 数据源后,需通过查看返回码确认是否请求成功。若返回 code 为 0,则数据连接成功;若返回其他 code,则数据连接失败。

成功示例


{
"code": 0,
"message": "成功",
"data": exampledata
}

失败示例


{
"code": 500,
"message": "错误信息"
}

登录鉴权


Swagger API 连接数据无鉴权,如需鉴权,联系系统管理员。

相关信息


有关缓存的更多信息,参见 配置数据源缓存