协议网关¶
协议网关负责运行网关逻辑,在接收到设备协议指定的相应数据后解析并生成模型/产品/设备数据或更新数据等等。生成的数据将在 EnOS 管理控制台中,通过如 MQTT 等等的设备协议完成设备数据的后续更新。
本章说明如何创建、查看、编辑、删除、开启/关闭、导出/导入协议网关。
前提条件¶
协议网关管理¶
创建协议网关¶
登录 EnOS 管理控制台,点击 IoT 协议连接器 > 协议网关 > 私有网关,即可看到已创建的协议网关列表。
点击 新增协议网关。
创建协议网关有两种方式。
从空白新增:填写全部协议网关的信息,详见下一步。
从模板新增:从 模板 下拉列表中选择一个模板,并填写协议网关信息,详见下一步。类型、网络组件 和 协议路由 将根据所选模板自动填充。所有可用模板与模板详情可在 协议网关 > 公有网关 查看。更多信息,参见 系统内置模板。
填写以下信息。
名称:输入协议网关的名称。若需要输入不同语言环境的自定义名称,点击 国际化 图标 。
类型:选择网络组件类型。
网络组件:选择网络组件,该选择将决定协议连接的方式。有关如何通过 MQTT/WebSocket 协议与 EnOS 建立连接,参见 通过 MQTT/WebSocket 协议与 EnOS 建立连接。
协议路由:点击 + URL 将 URL 路由映射到所指定的设备协议。输入以 “/” 开头的路由,并选择要与之映射的设备协议。可添加的最大路由数为 5。
设备协议的选择将决定数据的处理方式,通过对不同的路由分别配置设备协议,可以使同一个协议网关处理不同的请求从而实现不同的业务。例如:
HTTP 协议:分别配置 /createDevice 和 /updateModel 两个路由并选择相应的创建设备和更新模型的设备协议,则可在使用 HTTP 网络组件时通过发送 POST 请求的方式将数据发送至 http://URL/createDevice 或者 http://URL/updateModel 两个 URL,分别实现创建设备和更新模型的功能。
MQTT 和 WebSocket 协议:路由则是 topic。例如,/createDevice 的订阅主题是
/createDevice_reply
,发布主题是/createDevice
。
有关不同协议 URL 的生成方式,参见 URL 生成方式。
连接 Token 校验:若需在连接时进行 token 认证以提高安全性,则打开开关。如果需要进行 token 校验,则在连接时需要额外在 HTTP header 中填写 token 的信息,或在 MQTT/WebSocket client ID 里添加 token 的信息。有关 token 的生成方式以及连接时的使用方法,参见 Token 生成方式与使用。
Access Key 与 Secret Key:在 应用注册 中注册的应用的 access key 与 secret key,在这里将用于权限相关的校验,例如检查应用是否有创建设备的权限,或者是否有更新模型的权限等。
描述:输入对协议网关的描述。
点击 确定 创建协议网关,其创建后将具有系统生成 ID,显示在 私有网关 列表中。
查看协议网关¶
已创建的协议网关列表在 IoT 协议连接器 > 协议网关 中显示,显示的信息有创建网关的时间,网关的 ID,名称,各自的网络组件和状态(开启中,已开启,未开启,关闭,失败)。
从列表中寻找需要查看的协议网关,点击 查看 图标 。
协议网关的详细信息将显示在弹出窗口中。
编辑协议网关¶
进入 IoT 协议连接器 > 协议网关,从列表中寻找需要编辑的协议网关,点击 编辑 。处于 已开启 或 开启中 状态的协议网关不可编辑。
除 协议 ID 外,其他字段均可编辑。
编辑完成后,点击 确定 以保存修改内容。
导出协议网关 ¶
导出协议网关的详细信息后,可将其原样使用或对其进行编辑,再将其导入为新的协议网关。导出的格式为 JSON。
进入 IoT 协议连接器 > 协议网关,从列表中寻找需要导出的协议网关,点击 下载 图标 。
保存 JSON 文件。
导入协议网关¶
导入协议网关的文件格式为 JSON。有关所需的详细信息,可参见 导出协议网关 的文件。
进入 IoT 协议连接器 > 协议网关,点击 导入。
在弹出窗口中拖放 JSON 文件,或点击选择要上传的 JSON 文件。
点击 确定 以导入协议网关。
删除协议网关¶
进入 IoT 协议连接器 > 协议网关,从列表中寻找需要删除的协议网关,点击 … > 删除。
删除的协议网关不可恢复,确认后在弹出窗口中点击 删除。
分配运行资源¶
每个协议网关默认分配的运行资源为 1。若需要,可更改分配。
进入 IoT 协议连接器 > 协议网关,从列表中寻找待分配运行资源的协议网关。
点击 … > 运行配置。注:当协议网关的 状态 处于 开启中 或 已开启 时不能更改分配。
根据需求编辑 单实例运行资源。
单实例运行资源:表示每个协议网关消耗的计算资源(以 CU 计算)。逻辑较复杂的设备协议需要消耗较多计算资源,因此推荐为其分配更多的资源。单实例可分配的最大计算资源为 8 CU。
运行资源总数:OU 申请到的协议网关资源总数。
剩余资源:当前 OU 可用的剩余资源数。
点击 确定 以保存修改内容。
开启/关闭协议网关¶
进入 IoT 协议连接器 > 协议网关,从列表中寻找需要开启/关闭的协议网关,并点击 … > 开启网关/关闭网关。
状态列中的状态将相应更改。
当协议网关成功开启之后,则可以通过网络组件中定义的网络协议发送请求。
备注
点击开启后,等待大约 3-5 分钟左右,手动刷新页面,网关的状态将从 开启中 改为 已开启。
通过 MQTT/WebSocket 协议与 EnOS 建立连接 ¶
Client ID,username 和 password 的格式如下。
Client ID: {clientId}|securemode={secureMode},signmethod=sha256,connect-type={connectType}},access-token={token},protocol-gateway-id={protocolGateWayId},timestamp={timeStamp}|
Username: {deviceKey}&{productKey}
Password: toUpperCase(sha256({content}{deviceSecret}/{productSecret}))
Client ID
clientId
:必填项。可指定使用 MAC 地址或设备序列号。不可超过 64 字符。securemode
:必填项。表示所使用的安全模式。使用静态激活认证方式的设备,
securemode=2
使用动态激活认证方式的设备,
securemode=3
signmethod
:必填项,当前支持 sha256。表示使用 SHA256 签名算法。connect-type
:必填项。支持 integration 和 login。注:若使用 login,即使打开了 连接 Token 校验 开关,也不需 token 校验。access-token
:取决于是否打开了 连接 Token 校验 开关以及connect-type
是否 integration。如果两者都是,则为必填项。有关 token 的生成方式以及连接时的使用方法,参见 Token 生成方式与使用。protocol-gateway-id
:必填项,创建协议网关后系统生成的 ID。timestamp
:必填项。表示当前的时间的 UNIX 时间戳,单位为毫秒。
例如,Client ID 所需的各字段如下所示:
clientId
=id123456securemode
=2signmethod
=sha256connect-type
=integrationaccess-token
=44b1d16f9754e739206969b8e2d509bb328b20e2protocol-gateway-id
=607f884bc6b5090250d87321timestamp
=1619168502866
则 Client ID =
id123456|securemode=2,signmethod=sha256,connect-type=integration,access-token=44b1d16f9754e739206969b8e2d509bb328b20e2,protocol-gateway-id=607f884bc6b5090250d87321,timestamp=1619168502866|
Username:若 Client ID 里
connect-type
为 integration,用户名将根据 JAR 文件中解析的内容。若connect-type
为 login,格式将由deviceKey
、 “&”、productKey
三个要素拼接而成。deviceKey
:设备的 device key,可以在 EnOS 管理控制台上获取。productKey
:设备的 product key,可以在 EnOS 管理控制台上获取。
例如,某设备的
deviceKey
为xIhSzeP6lh
,productKey
为Yj9MEH5F
。则此处的 Username 将为xIhSzeP6lh&Yj9MEH5F
。
Password:若 Client ID 里
connect-type
为 integration,密码将根据 JAR 文件中解析的内容。若connect-type
为 login,格式如下。静态激活的设备,由
content
与deviceSecret
拼接而成;动态激活的设备,由content
与productSecret
拼接而成。然后将拼接得来的字符串用 SHA256 算法计算出新的字符串,再将新的字符串的字母全部转换成大写字母。content
:按照clientId
,deviceKey
,productKey
,timestamp
的顺序,将字段名称和值串联组合。例如:设备的参数值如下所示
clientId
= id123456deviceKey
= dK987654productKey
= pK11111timestamp
= 1234567890
则
content
=clientIdid123456deviceKeydK987654productKeypK11111timestamp1234567890
URL 生成方式 ¶
不同协议 URL 的生成方式如以下,其中{address}
和 {port}
可在登录 EnOS 管理控制台后点击右上角的 帮助 > 环境信息,第三方网关连接 中获取。
HTTP:
http://{protocolGatewayId}.{address}:{port}{path}
protocolGatewayId: 成功创建协议网关时系统生成的 ID,例如:
60ffd12940c3768039f6aa55
.path:创建协议网关时填写的 协议路由,例如:
/createDevice
。
WebSocket:
ws://{address}:{port}/mqtt
MQTT:
tcp://{address}:{port}
使用以上的示例,生成在 beta 环境 HTTP 协议的 URL 将为 http://60ffd12940c3768039f6aa55.third-party-protocol-beta1.eniot.io:9091/createDevice
。
Token 生成方式与使用 ¶
生成 token 的格式:
sha1(accessKey+accessSecret+timestamp)
accessKey:创建协议网关时输入的 access key,例如:
abc
。secretKey:创建协议网关时输入的 secret key,例如:
xyz
。timestamp:Request 的 header 中的 timestamp 字段,例如:
1619168502866
。
将以上值拼接成一字符串。
使用 SHA1 算法将字符串进行编码,并转换为小写。
sha1 ("abcdxyz1619168502866")
获得的 token 将是
44b1d16f9754e739206969b8e2d509bb328b20e2
。不同协议使用 token 的方式不一样。
HTTP:发送时 HTTP 请求的 header 必须符合如下格式。
{ accessToken: 44b1d16f9754e739206969b8e2d509bb328b20e2, timestamp: 1619168502866 }
WebSocket 和 MQTT:使用 token 作为 Client ID 中
access-token
参数的值。更多信息,参见 通过 MQTT/WebSocket 协议与 EnOS 建立连接。