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

应用集成效果

完成应用集成后,应用的功能菜单将会融入到“工业互联网企业级平台(数字工厂)”的左侧导航栏。例如“A生产管理应用”这个集成后如下图:首页

提供接口方式

  • 协议
  • 服务的url

注意:应用描述接口的访问路径建议使用应用相对路径/appconfig,这样能够实现自动集成到数字工厂,如果采用其他的访问路径,需要在数字工厂中应用集成中进行应用安装和配置手动集成。

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

服务URL默认https://test.com/appconfig?appId=xxxx,appId为标识哪个租户调用该应用描述接口,可以根据不同的租户提供不同的配置。

  • 返回参数
参数 类型 描述
code Integer 调用成功返回200;若调用失败返回203
message String code返回203时填写具体失败原因,code返回200填写success
data json 应用描述
  • 返回参数示例
{
  "code": 200,
  "message": "success",
  "data": {
    "appName": "A生产管理应用",
    "urlprefix": "https://abc.com",
    "appConfigPath": "/appconfig",
    "appDomain": "生产制造",
    "features": [
      {
        "name": "生产管理",
        "resType": "directory",
        "modules": [
          {
            "name": "查看生产计划",
            "resType": "page",
            "resId": "queryAllWorkorders",
            "path": "/queryAllWorkorders",
            "layoutMode": "workspace"
          },
          {
            "name": "确认生产计划",
            "resType": "page",
            "resId": "confirmWorkorder",
            "path": "/confirmWorkorder",
            "layoutMode": "workspace",
            "authorities": [
              {
                "name": "终止生产计划",
                "resType": "authority",
                "resId": "terminateOrder",
                "authorities": [
                  {
                    "name": "终止生产计划二次确认",
                    "resType": "authority",
                    "resId": "terminateOrderConfirm"
                  }
                ]
              }
            ]
          },
          {
            "name": "查看生产计划执行结果",
            "resType": "page",
            "resId": "queryWorkorderResults",
            "path": "/queryWorkorderResults",
            "layoutMode": "workspace",
            "authorities": [
              {
                "name": "查看已下发生产计划",
                "resType": "authority",
                "resId": "queryConfirmedOrder",
                "authorities": [
                  {
                    "name": "查看已终止生产计划",
                    "resType": "authority",
                    "resId": "queryTerminatedOrder"
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "name": "质量管理",
        "resType": "directory",
        "modules": [
          {
            "name": "查看质检结果",
            "resType": "page",
            "resId": "queryQCResults",
            "path": "/queryQCResults",
            "layoutMode": "workspace"
          }
        ]
      },
      {
        "name": "应用管理权限",
        "resType": "authority",
        "resId": "appadmin"
      }
    ],
    "specialpages": [
      {
        "type": "configuration",
        "path": "/config"
      },
      {
        "type": "help",
        "path": "/help"
      },
      {
        "type": "description",
        "path": "/description"
      }
    ],
    "dependencies": {
    "masterData": [
      {
        "name": "物料",
        "properties": [
          {
            "propertyCode": "code",
            "propertyDesc": "物料编码",
            "propertyType": "STRING",
            "propertyLimit": {
              "min": 1.0,
              "max": 100,
              "len": 64,
              "factoryType": "FACTORY",
              "technologyType": "TECHNOLOGY",
              "warehouseType": "WAREHOUSE",
              "enumValues": [
                {
                  "value": "0",
                  "remark": "早班"
                },
                {
                  "value": "1",
                  "remark": "中班"
                },
                {
                  "value": "2",
                  "remark": "晚班"
                }
              ],
              "booleanValues": [
                {
                  "value": "1",
                  "remark": "真"
                },
                {
                  "value": "0",
                  "remark": "假"
                }
              ]
            },
            "isUnique": 1,
            "isNull": 1,
            "defaultValue": "xxx"
          }
        ]
      }
    ]
  }
  }
}

描述接口格式

工业应用接入阿里云工业互联网平台,首先实现应用托管要求的接口,例如对共享式Saas应用,需要实现免密登录(GetSSOUrl)、生产租户(CreateInstance)、注销租户(DeleteInstance)等服务,详细要求参考SaaS应用对接

然后对于需要实现一个获取应用描述接口的服务,说明应用的基本信息。应用配置包括“基础信息”、“功能配置”、“特殊页面”、“资源依赖”这几个部分,分别说明如下:

  1. 基础信息

    描述工业应用的基础信息:

    参数名称 参数说明 参数示例
    appName 描述工业应用名称,不超过64个字符 生产管理
    urlprefix 访问该应用的路径,不超过800字符 https://abc.com
    appConfigPath 访问该工业应用的描述接口的相对路径,如果是多租户SaaS将以urlprefix为路径前缀,如果是独占式应用以应用实例部署后的访问路径为前缀,不超过800字符 /appconfig
    appDomain 说明应用属于哪一个域如果没有说明,默认为生产制造域,可选择:供应链管理|研发设计|生产制造|运营管理|仓储物流|运维服务 供应链管理
  2. 功能配置
    功能配置列出该应用哪些页面和权限控制点需要集成到数字工厂中,集成的功能分成三种类型:
    1. 目录(resType=directory):显示在数字工厂该应用域的导航菜单中,对页面进行分组用,目录下级可以继续声明目录和页面类型的配置;
    2. 页面(resType=page):页面作为目录的下级菜单,访问路径为整合到门户以后,数字中心访问该应用页面的相对路径,页面下级可以继续声明权限类型的配置;
    3. 权限(resType=authority):鉴权资源列表列出该应用需要进行权限控制的功能点,鉴权资源可以是页面级也可以是按钮级甚至是数据级,页面下级可以继续声明权限类型的配置。

    目录的配置详细说明:

    参数名称 参数说明 参数示例
    name 目录名称 生产管理
    modules 下级功能,包括目录、页面和权限 功能的json

    Json表达方式为:

    {
        "name": "生产管理",
        "resType": "directory",
        "modules": [
              {
                "name": "查看生产计划",
                "resType": "page",
                "resId": "queryAllWorkorders",
                "path": "/queryAllWorkorders",
                "layoutMode": "workspace"
              }
        ]
    }

    页面的配置详细说明:

    参数名称 参数说明 参数示例
    name 页面集成后显示的菜单名称和权限名称 确认生产计划
    resId resId作为一个整体名字空间,命名应该唯一,建议长度在32个字符内,最大不能超过40个字符 confirmWorkorder
    path 页面访问路径,不能超过800字符,页面整合到导航中必须实现https而不是http协议 /confirmWorkorder
    layoutMode 页面显示方式,可选择:workspace|fullscreen。workspace显示区域为工作区,左边应用导航菜单不隐藏,该模式为默认模式;fullscreen,设置该页面显示区域为全屏,左边应用导航菜单自动隐藏,该模式适合只集成单个控制台页面 workspace
    authorities 属于该页面的子权限 授权的Json

    Json表达方式为:

    {
                "name": "确认生产计划",
                "resType": "page",
                "resId": "confirmWorkorder",
                "path": "/confirmWorkorder",
                "layoutMode": "workspace",
                "authorities": [
                  {
                    "name": "终止生产计划",
                    "resType": "authority",
                    "resId": "terminateOrder",
                    "authorities": [
                      {
                        "name": "终止生产计划二次确认",
                        "resType": "authority",
                        "resId": "terminateOrderConfirm"
                      }
                    ]
                  }
    }

    权限的配置详细说明:

    参数名称 参数说明 参数示例
    name 权限的名称 终止生产计划
    resId resId作为一个整体名字空间,命名应该唯一,建议长度在32个字符内,最大不能超过40个字符 terminateOrder
    authorities 属于该权限的子权限 授权的Json

    Json表达方式为:

    {
                  {
                    "name": "终止生产计划",
                    "resType": "authority",
                    "resId": "terminateOrder",
                    "authorities": [
                      {
                        "name": "终止生产计划二次确认",
                        "resType": "authority",
                        "resId": "terminateOrderConfirm"
                      }
                    ]
                  }
    }
  3. 特殊页面

    为提高应用的易用性,应用可以通过描述接口来发布特殊功能的页面,现在描述接口支持三类特殊功能页面:应用配置页面(类型:CONFIGURATION);应用帮助页面(类型:HELP);应用详情介绍(类型:DESCRIPTION)

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

    应用帮助页面将出现在数字工厂中的帮助页面和应用详情介绍。如果没有相应的页面配置,前端将不会显示,例如下面这个配置会显示“详情”和“设置”,不会显示“帮助”。

     "specialpages": [
            {
                "type": "configuration",
                "path": "/config"
            },
            {
                "type": "description",
                "path": "/description"
            }
        ]
  4. 资源依赖

    dependencies部分用于描述应用对资源的依赖,其中masterData用来指定应用对元数据的依赖,如果数字工厂开通应用后中没有定义元数据则会自动创建。被依赖的元数据定义用户将不能在编辑元数据修改或者删除。

    元数据定义包括了名称和属性定义,Json结构示例如下:

    "masterData": [{
        "name": "物料", // 主数据名称,必填
        // 元数据的属性列表
        "properties": [{
            "propertyCode": "code", // 属性标识,必填
            "propertyDesc": "物料编码",
            "propertyType": "STRING" / "INTEGER" / "DOUBLE" / "ENUM" / "FACTORY" / "TECHNOLOGY" / "WAREHOUSE", // 属性类型,必填
            // 属性的限制描述
            "propertyLimit": {
                // 属性类型为INTEGER/DOUBLE时,这两个字段有效,值为浮点数
                "min": 1.0,
                "max": 100,
                // 属性类型为STRING时,这个限制字符串的长度
                "len": 64,
                // 属性类型为工厂模型时,这个字段表示具体的工厂节点类型
                "factoryType": "FACTORY" / "WORKSHOP" / "BELTLINE" / "MACHINING_CENTER",
                // 属性类型为工艺路径时,这个字段表示具体的工艺路径的节点类型
                "technologyType": "TECHNOLOGY" / "PROCESS" / "STEP",
                // 属性类型为库存地点时,这个字段表示具体的库存节点类型
                "warehouseType": "WAREHOUSE" / "AREA" / "LOCATION",
                // 属性类型为ENUM时,这个记录枚举的所有值
                "enumValues": [{
                    "value": "0",
                    "remark": "早班"
                }, {
                    "value": "1",
                    "remark": "中班"
                }, {
                    "value": "2",
                    "remark": "晚班"
                }],
                // 属性类型为BOOLEAN时,这个记录布尔值
                "booleanValues": [{
                    "value": "1",
                    "remark": "真"
                }, {
                    "value": "0",
                    "remark": "假"
                }]
            },
            "isUnique": 1 / 0, // 是否唯一键
            "isNull": 1 / 0, // 是否可空
            "defaultValue": "xxx", // 默认值,不管属性是什么类型,这里都用字符串
        }]
    }]

访问应用页面

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

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相关的说明也可以参考:

为工业业务提供具体业务所使用的各类资源的定义功能,可以针对需要进行访问管控的资源进行不同级别的定义

第三方页面打开数字工厂首页tab的方法

1、CDN方式
<!DOCTYPE html>
<html lang="en">

<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>三方页面通讯demo</title>

  <script src="https://iotx-components.oss-cn-beijing.aliyuncs.com/components-utils/1.0.0/message_client.js"></script>
</head>

<body>

  <button onclick="openTab()">打开链接</button>

  <script>
    const client = new IotxMessageClient.default();
    client.init();

    const openTab = () => {
      const prefix = window.location.protocol + "//" + window.location.host;
      client.sendMsg('THIRD_DOMAIN', { url: prefix + '/importorder' }, ({ allow }) => {
        if (allow) {
          console.log('成功打开tab')
        } else {
          // 可以做一些失败逻辑,如window.open
          console.log('false')
        }
      });
    }

  </script>

</body>

</html>
2、npm方式
  • 安装sdk
    npm install --save @iotx/components-utils
  • 初始化sdk
    import { MessageClient } from '@iotx/components-utils';
    
    this.client = new MessageClient();
    this.client.init();
  • 打开url,url为已集成数字工厂应用下的url,示例如下:
    // 打开指定页面,已指定页面的路径为/importorder为例
    const prefix = window.location.protocol + "//" + window.location.host;
    this.client.sendMsg('THIRD_DOMAIN', {
      url: prefix + '/importorder',
    }, ({ allow }) => {
      // allow  为true时,表示访问白名单内,支持直接打开,否则不支持打开
      // 其他业务逻辑
    })