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

应用集成效果

完成应用集成后,应用的功能菜单将会融入到“工业互联网企业级平台(数字工厂)”的左侧导航栏。例如“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": "生产制造" //说明应用属于哪一个域如果没有说明,默认为生产制造域,可选择:供应链管理|研发设计|生产制造|运营管理|仓储物流|运维服务
        "resources": [
            {
                "resCode": "queryAllOrder",
                "name": "查看生产计划"
            },
            {
                "resCode": "terminateOrder",
                "name": "终止生产计划"
            },
            {
                "resCode": "queryConfirmedOrder",
                "name": "查看已下发生产计划"
            }
        ],
        "navigators": [
            {
                "module": "生产管理",
                "page": "查看生产计划",
                "pageId": "queryAllWorkorders",
                "path": "/queryAllWorkorders",
                "layoutMode":"workspace" //设置该页面显示区域为工作区,左边应用导航菜单不隐藏,该模式为默认模式 
            },
            {
                "module": "生产管理",
                "page": "确认生产计划",
                "pageId": "confirmWorkorder",
                "path": "/confirmWorkorder"
            },
            {
                "module": "生产管理",
                "page": "查看生产计划执行结果",
                "pageId": "queryWorkorderResults",
                "path": "/queryWorkorderResults",
                "layoutMode":"fullscreen" //设置该页面显示区域为全屏,左边应用导航菜单自动隐藏,该模式适合只集成单个控制台页面
            }
        ],
        "specialpages": [
            {
                "type": "configuration",
                "path": "/config"
            },
            {
                "type": "help",
                "path": "/help"
            },
            {
                "type": "description",
                "path": "/description"
            }
        ],
        "dependencies": {
          "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,
                // 属性类型为FACTORY时,这个字段表示具体的工厂节点类型
                "factoryType": "FACTORY"/"WORKSHOP"/"BELTLINE"/"MACHINING_CENTER",
                // 属性类型为TECHNOLOGY时,这个字段表示具体的工艺路径的节点类型
                "technologyType": "TECHNOLOGY"/"PROCESS"/"STEP",
                // 属性类型为WAREHOUSE时,这个字段表示具体的库存节点类型
                "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",// 默认值,不管属性是什么类型,这里都用字符串
            }]
          }]
        }
    }
}

描述接口格式

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

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

  1. 基础信息

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

    参数名称 参数说明 参数示例
    appName 描述工业应用名称,不超过64个字符 生产管理
    urlprefix 访问该应用的路径,不超过800字符 https://abc.com
    appConfigPath 访问该工业应用的描述接口的相对路径,如果是多租户SaaS将以urlprefix为路径前缀,如果是独占式应用以应用实例部署后的访问路径为前缀,不超过800字符 /appconfig
    appDomain 说明应用属于哪一个域如果没有说明,默认为生产制造域,可选择:供应链管理|研发设计|生产制造|运营管理|仓储物流|运维服务 供应链管理
  2. 导航配置

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

    参数名称 参数说明 参数示例
    module 描述该页面归属哪个模块下面,可以实现多级模块,最多三级,中间用“/”隔开,每个模块不超过32字符 生产管理/生产计划
    page 显示的页面名称,命名应该唯一,长度不超过64个字符 查看生产计划
    pageId pageId与resources的resCode字段作为一个整体名字空间,命名应该唯一,长度不超过40个字符 /appconfig
    path 页面访问路径,不能超过800字符,页面整合到导航中必须实现https而不是http协议 /queryAllWorkorders
    layoutMode 页面显示方式,可选择:workspace|fullscreen。workspace显示区域为工作区,左边应用导航菜单不隐藏,该模式为默认模式;fullscreen,设置该页面显示区域为全屏,左边应用导航菜单自动隐藏,该模式适合只集成单个控制台页面 workspace

    Json表达方式为:

    [
            {
                    "module": "生产管理",
                    "page": "查看生产计划",
                    "pageId": "queryAllWorkorders",
                    "path": "/queryAllWorkorders",
                    "layoutMode":"workspace" //设置该页面显示区域为工作区,左边应用导航菜单不隐藏,该模式为默认模式 
                },
                {
                    "module": "生产管理",
                    "page": "确认生产计划",
                    "pageId": "confirmWorkorder",
                    "path": "/confirmWorkorder"
                },
                {
                    "module": "生产管理",
                    "page": "查看生产计划执行结果",
                    "pageId": "queryWorkorderResults",
                    "path": "/queryWorkorderResults",
                    "layoutMode":"fullscreen" //设置该页面显示区域为全屏,左边应用导航菜单自动隐藏,该模式适合只集成单个控制台页面
                }
    ]
  3. 鉴权资源

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

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

    参数名称 参数说明 参数示例
    resCode 资源标识,可以由字母/数字/中划线“-”组成,资源标识必须当前应用内唯一,且不能与导航配置的pageId相同,长度不个45个字符 terminateOrder
    name 资源描述名称,长度不个64个字符 终止生产计划
    [
      {
        "resCode: ": "queryAllOrder",
        "name": "查看生产计划"
      },
      {
        "resCode: ": "terminateOrder",
        "name": "终止生产计划"
      },
      {
        "resCode: ": "queryConfirmedOrder",
        "name": "查看已下发生产计划"
      }
    ]
  4. 特殊页面

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

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

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

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

    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时,表示访问白名单内,支持直接打开,否则不支持打开
      // 其他业务逻辑
    })