第三方应用需要实现一个应用自描述的接口，它是将三方应用集成到工业互联网企业级平台（数字工厂）的桥梁。企业用户在物联网市场中订购应用以后，通过“工业互联网企业级平台（数字工厂）”或“集成工作台”的“应用集成”功能加载应用自描述接口内容，对应用进行集成。本文中的“应用描述接口”也称做“应用配置”。
应用集成效果
提供接口方式
- 协议
- 服务的url
注意：应用描述接口的访问路径建议使用应用相对路径/appconfig，这样能够实现自动集成到数字工厂，如果采用其他的访问路径，需要应用安装和配置在数字工厂中应用集成中进行手动集成。
由域名和服务路径拼接成服务的URL，例如应用的域名为https://****.com
服务URL默认https://****.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应用对接。
然后对于需要实现一个获取应用描述接口的服务，说明应用的基本信息。应用配置包括“基础信息”、“功能配置”、“特殊页面”、“资源依赖”这几个部分，分别说明如下：
- 基础信息
描述工业应用的基础信息：
参数名称 参数说明 参数示例 appName 描述工业应用名称，不超过64个字符 生产管理 urlprefix 访问该应用的路径，不超过800字符 https://***.com appConfigPath 访问该工业应用的描述接口的相对路径，如果是多租户SaaS将以urlprefix为路径前缀，如果是独占式应用以应用实例部署后的访问路径为前缀，不超过800字符 /appconfig appDomain 说明应用属于哪一个域如果没有说明，默认为生产制造域，可选择：供应链管理|研发设计|生产制造|运营管理|仓储物流|运维服务 供应链管理 - 功能配置功能配置列出该应用哪些页面和权限控制点需要集成到数字工厂中，集成的功能分成三种类型：
- 目录（resType=directory）：显示在数字工厂该应用域的导航菜单中，对页面进行分组用，目录下级可以继续声明目录和页面类型的配置；
- 页面（resType=page）：页面作为目录的下级菜单，访问路径为整合到门户以后，数字中心访问该应用页面的相对路径，页面下级可以继续声明权限类型的配置；
- 权限（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" } ] } } - 特殊页面
为提高应用的易用性，应用可以通过描述接口来发布特殊功能的页面，现在描述接口支持三类特殊功能页面：应用配置页面（类型：CONFIGURATION）；应用帮助页面（类型：HELP）；应用详情介绍（类型：DESCRIPTION）
应用配置页面将出现在数字工厂中的应用配置页面：
应用帮助页面将出现在数字工厂中的帮助页面和应用详情介绍。如果没有相应的页面配置，前端将不会显示，例如下面这个配置会显示“详情”和“设置”，不会显示“帮助”。
"specialpages": [ { "type": "configuration", "path": "/config" }, { "type": "description", "path": "/description" } ] - 资源依赖
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://****.com/user/login？token=xxxx&oauth_callback=https://****.com/module/page
其中，
“https://****.com/user/login？token=xxxx”是通过免密登录URI返回的免密url,
“https://****.com/module/page”是appconfig配置中urlPrefix与path拼接成的资源的访问路径。
应用里面需要解析“oauth_callback”关键字进行跳转。
2、独占式应用的页面
独占式应用按Oauth2.0实现免密登录，url分为2个部分：
- 域名及登录验证信息
- 页面url路径
例如：https://****.com/module/page？code=xxxxxx
其中，
https：//****.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的方法
<!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>- 安装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时，表示访问白名单内，支持直接打开，否则不支持打开 // 其他业务逻辑 })