实现应用描述接口_交互框架集成_工业应用集成

第三方应用需要实现一个应用自描述的接口，它是将三方应用集成到工业互联网企业级平台（数字工厂）的桥梁。企业用户在物联网市场中订购应用以后，通过“工业互联网企业级平台（数字工厂）”或“集成工作台”的“应用集成”功能加载应用自描述接口内容，对应用进行集成。本文中的“应用描述接口”也称做“应用配置”。

应用集成操作

在应用购买、支付、生产、域名配置（独占式应用）这些操作完成后，需要将应用集成到“工业互联网企业级平台（数字工厂）”。

获取应用的配置
单击“确定”进行集成

应用集成效果

完成应用集成后，应用的功能菜单将会融入到“工业互联网企业级平台（数字工厂）”的左侧导航栏。例如“工业共享式SaaS应用demo”这个集成后如下图：

提供接口方式

协议

服务路径

/appconfig

说明：不用登录直接可以访问这个路径。

服务的url

由域名和服务路径拼接成服务的URL，例如应用的域名为https://test.com

服务URL默认https://test.com/appconfig。

返回参数

正常返回参数实例

{
    "code": 200,
    "message": "success",
    "data": {
        "appName": "某某应用",
        "urlprefix": "https://abc.com",
        "resources": [
          {
            "resCode": "queryAllOrder",
            "name": "查看生产计划"
          },
          {
            "resCode": "terminateOrder",
            "name": "终止生产计划"
          },
          {
            "resCode": "queryConfirmedOrder",
            "name": "查看已下发生产计划"
          }
      ],
        "navigators": [
        {
         "module": "生产调度",
         "page": "查看生产计划",
         "pageId": "queryAllWorkorders",
         "path": "/queryAllWorkorders"
        },
        {
         "module": "生产调度",
         "page": "确认生产计划",
         "pageId": "confirmWorkorder",
         "path": "/confirmWorkorder"
        },
        {
         "module": "生产调度",
         "page": "查看生产计划执行结果",
         "pageId": "confirmWorkorder",
         "path": "/queryWorkorderResults"
        }
      ],
      "specialpages": [
          {
            "type": "configuration",
            "path": "/config"
          },
          {
            "type": "help",
            "path": "/help"
          },
          {
            "type": "description",
            "path": "/description"
          }
      ]
    }
}

描述接口格式

阿里云应用托管平台对工业平台三方应用的接入，有两部分的要求：

托管平台的要求

托管平台会对所有行业的应用有通用的要求，例如对共享式Saas应用，

需要实现免密登录（GetSSOUrl）、生产租户（CreateInstance）、注销租户（DeleteInstance）等服务，详细要求参考《应用托管多租户SaaS对接方案》。

工业平台的要求

对于工业类型的应用需要实现一个获取应用描述接口的服务，对外提供应用配置。

应用配置格式：

{
    "appName": "某某应用",
    "urlprefix": "https://abc.com",
    "resources": [
        {
            "resCode": "queryAllOrder",
            "name": "查看生产计划"
        },
        {
            "resCode": "terminateOrder",
            "name": "终止生产计划"
        },
        {
            "resCode": "queryConfirmedOrder",
            "name": "查看已下发生产计划"
        }
    ],
    "navigators": [
        {
            "module": "生产调度",
            "page": "查看生产计划",
            "pageId": "queryAllWorkorders",
            "path": "/queryAllWorkorders"
        },
        {
            "module": "生产调度",
            "page": "确认生产计划",
            "pageId": "confirmWorkorder",
            "path": "/confirmWorkorder"
        },
        {
            "module": "生产调度",
            "page": "查看生产计划执行结果",
            "pageId": "confirmWorkorder",
            "path": "/queryWorkorderResults"
        }
    ],
    "specialpages": [
        {
            "type": "configuration",
            "path": "/config"
        },
        {
            "type": "help",
            "path": "/help"
        },
        {
            "type": "description",
            "path": "/description"
        }
    ]
}

说明：

resources的resCode字段可以由字母/数字/中划线“-”组成；
navigators的pageId字段，与resources的resCode字段作为一个整体名字空间，命名应该唯一，不可以重复。
navigators的page字段、module字段会在前端显示出来，建议用中文。

应用配置包括“导航配置”、“鉴权资源”、“特殊页面”这几个部分，分别说明如下：

（1）导航配置

导航配置列出该应用哪些一级页面需要集成到数字工厂的门户中。导航配置中的模块名称，是在导航配置页面的时候对页面进行分组用；页面名称为显示的页面名称；访问路径为整合到门户以后，数字中心访问该应用页面的相对路径。

注：如果页面整合到导航中必须实现https而不是http协议。


模块名称 module	页面名称 page	访问路径 path
生产调度	查看生产计划	/queryAllWorkorders
生产调度	确认生产计划	/confirmWorkorder
生产调度	查看生产计划执行结果	/queryWorkorderResults

Json表达方式为：

[{
 "module: ": "生产调度",
 "page": "查看生产计划",
 "pageId": "queryAllWorkorders",
 "path": "/queryAllWorkorders"
},
{
 "module: ": "生产调度",
 "page": "确认生产计划",
 "pageId": "confirmWorkorder",
 "path": "/confirmWorkorder"
},
{
 "module: ": "生产调度",
 "page": "查看生产计划执行结果",
 "pageId": "confirmWorkorder",
 "path": "/queryWorkorderResults"
}]

（2）鉴权资源

鉴权资源列表列出该应用需要进行权限控制的功能点，鉴权资源可以是页面级也可以是按钮级甚至是数据级。

例如在生产管理中有一个页面是查看生产计划，并不是所有的用户都可以查看生产计划，需要把这个查看生产计划作为一个页面鉴权；在查看生产计划页面上有一个按钮为“终止计划”，这个需要分配给高级别的调度角色才能使用；车间主任只能查看已经确认下发的生产计划，其他状态的生产计划不能查看。以上的场景需要应用声明三个鉴权资源：


资源标识 resCode	资源名称 name
queryAllOrder	查看生产计划
terminateOrder	终止生产计划
queryConfirmedOrder	查看已下发生产计划

注意：资源标识必须当前应用内唯一，且不能与导航配置的pageId相同，后台通过资源标识+应用id生成全局唯一资源标识。

[
  {
    "resCode: ": "queryAllOrder",
    "name": "查看生产计划"
  },
  {
    "resCode: ": "terminateOrder",
    "name": "终止生产计划"
  },
  {
    "resCode: ": "queryConfirmedOrder",
    "name": "查看已下发生产计划"
  }
]

（3）特殊页面

为提高应用的易用性，应用可以通过描述接口来发布特殊功能的页面，现在描述接口支持三类特殊功能页面：

应用配置页面（类型：CONFIGURATION）；应用帮助页面（类型：HELP）；应用详情介绍（类型：DESCRIPTION）

应用配置页面将出现在数字工厂中的应用配置页面：

应用帮助页面将出现在数字工厂中的帮助页面和应用详情介绍。

如果没有相应的页面配置，前端将不会显示，例如下面这个配置会显示“详情”和“设置”，不会显示“帮助”。

 "specialpages": [
        {
            "type": "configuration",
            "path": "/config"
        },
        {
            "type": "description",
            "path": "/description"
        }
    ]

访问应用页面

集成到“工业互联网企业级平台（数字工厂）”后，可以通过左侧导航栏访问应用的页面。

1、共享式应用的页面

共享式应用按ssoURL方式实现免密登录，url分2个部分：

域名及登录验证信息
页面的url路径

例如：https://test.com/user/login？token=xxxx&oauth_callback=https://test.com/module/page

其中，

“https://test.com/user/login？token=xxxx”是通过免密登录URI返回的免密url,

“https://test.com/module/page”是appconfig配置中urlPrefix与path拼接成的资源的访问路径。

应用里面需要解析“oauth_callback”关键字进行跳转。

2、独占式应用的页面

独占式应用按Oauth2.0实现免密登录，url分为2个部分：

域名及登录验证信息
页面url路径

例如：https://test.com/module/page？code=xxxxxx

其中，

https：//test.com/module/page是页面的路径；

code=xxxxxx是登录验证信息。

应用资源鉴权

应用可以自定义权限，限制不同角色的用户对应用的访问。例如应用在查看生产计划的页面中编写一段脚本，根据当前登录的账号是否有“终止生产计划”的权限，通过这个判断”终止生产计划“这个按钮是否disable。可以分3个步骤：

在应用描述接口中定义鉴权资源，例如把“终止生产计划”作为一个鉴权资源；
通过“工业互联网企业级平台（数字工厂）”或“集成工作台”的“角色管理”功能，把这个资源授权给角色；
在应用里面，调用资源鉴权API，查询用户的访问权限，并做访问控制。

1、平台上资源授权

完成应用集成后，应用描述接口中的“鉴权资源”将会显示在“角色管理”的“访问权限”列表中。

通过“工业互联网企业级平台（数字工厂）”或“集成工作台”的“角色管理”功能，将应用定义的资源授权给相应的角色。

2、应用内资源鉴权

资源鉴权API

请求参数

返回参数

正常返回示例

{
  "id": "70333b89-3302-4006-8559-cf6d345ae52c",
  "code": 200,
  "message": "success",
  "localizedMsg": null,
  "data": true/false
}