准备与添加 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 连接数据无鉴权，如需鉴权，联系系统管理员。