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

应用集成效果

完成应用集成后,应用的功能菜单将会融入到“工业互联网企业级平台(数字工厂)”的左侧导航栏。例如“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",
        "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": "queryWorkorderResults",
                "path": "/queryWorkorderResults"
            }
        ],
        "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说明工业应用名称,
    • appName:说明工业应用名称
    • urlprefix:如果是多租户SaaS为访问该应用的路径
    • appConfigPath:访问该工业应用的描述接口的相对路径,如果是多租户SaaS将以urlprefix为路径前缀,如果是独占式应用以应用实例部署后的访问路径为前缀
  2. 导航配置

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

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

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

    注:module可以实现多级模块,最多三级,第一级为应用名称,第二级为模块名称,第三级为页面名称;pageId与resources的resCode字段作为一个整体名字空间,命名应该唯一,不可以重复;navigators的page字段、module字段会在前端显示出来,建议用中文。

    Json表达方式为:

    [
            {
            "module": "生产管理",
            "page": "查看生产计划",
            "pageId": "queryAllWorkorders",
            "path": "/queryAllWorkorders"
        },
        {
            "module": "生产管理",
            "page": "确认生产计划",
            "pageId": "confirmWorkorder",
            "path": "/confirmWorkorder"
        },
        {
            "module": "生产管理",
            "page": "查看生产计划执行结果",
            "pageId": "queryWorkorderResults",
            "path": "/queryWorkorderResults"
        }
    ]
  3. 鉴权资源

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

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

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

    注意:resources的resCode字段可以由字母/数字/中划线“-”组成,资源标识必须当前应用内唯一,且不能与导航配置的pageId相同,后台通过资源标识+应用id生成全局唯一资源标识。

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

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