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

应用集成操作

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

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

应用集成效果

完成应用集成后,应用的功能菜单将会融入到“工业互联网企业级平台(数字工厂)”的左侧导航栏。例如“工业共享式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
}

这个API相关的说明也可以参考:

https://dev.iot.aliyun.com/api_center/detail/2176?sceneName=工业云端开放服务&serviceId=2965&idx=1