协议网关¶

协议网关负责运行网关逻辑，在接收到设备协议指定的相应数据后解析并生成模型/产品/设备数据或更新数据等等。生成的数据将在 EnOS 管理控制台 中，通过如 MQTT 等等的设备协议完成设备数据的后续更新。

本章说明如何创建、查看、编辑、删除、开启/关闭、导出/导入协议网关。

开始前准备¶

你需要设备管理员角色的权限。如果没有请联系组织管理员添加，参见策略，角色，与权限。
确保已创建网络组件与设备协议。
确保已在 EnOS 管理控制台 > 资源管理 > 资源列表 申请了协议网关资源。有关请求资源的更多信息，参见 EnOS 上的资源。

协议网关管理¶

创建协议网关¶

登入 EnOS 管理控制台，点击 设备接入 > 协议网关 > 私有网关，即可看到已创建的协议网关列表。
点击 新增协议网关。
创建协议网关有两种方式。
- 从空白新增：填写全部协议网关的信息，详见下一步。
- 从模板新增：从模板下拉列表中选择一个模板，并填写协议网关信息，详见下一步。类型、网络组件 和 协议路由 将根据所选模板自动填充。所有可用模板与模板详情可在 协议网关 > 公有网关 查看。更多信息，参见系统内置模板。
填写以下信息。
- 名称：输入协议网关的名称。若需要输入不同语言环境的自定义名称，点击 国际化 图标。
- 类型：选择网络组件类型。
- 网络组件：选择网络组件，该选择将决定协议连接的方式。有关如何通过 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，显示在 私有网关 列表中。

查看协议网关¶

已创建的协议网关列表在 设备接入 > 协议网关 中显示，显示的信息有创建网关的时间，网关的 ID，名称，各自的网络组件和状态（开启中，已开启，未开启，关闭，失败）。
从列表中寻找需要查看的协议网关，点击查看图标。
协议网关的详细信息将显示在弹出窗口中。

编辑协议网关¶

进入 设备接入 > 协议网关，从列表中寻找需要编辑的协议网关，点击编辑图标。处于 已开启 或 开启中 状态的协议网关不可编辑。
除 协议 ID 外，其他字段均可编辑。
编辑完成后，点击确定以保存修改内容。

导出协议网关 ¶

导出协议网关的详细信息后，可将其原样使用或对其进行编辑，再将其导入为新的协议网关。导出的格式为 JSON。

进入 设备接入 > 协议网关，从列表中寻找需要导出的协议网关，点击下载图标。
保存 JSON 文件。

导入协议网关¶

导入协议网关的文件格式为 JSON。有关所需的详细信息，可参见导出协议网关的文件。

进入 设备接入 > 协议网关，点击导入。
在弹出窗口中拖放 JSON 文件，或点击选择要上传的 JSON 文件。
点击确定以导入协议网关。

删除协议网关¶

进入 设备接入 > 协议网关，从列表中寻找需要删除的协议网关，点击删除图标。
删除后的协议网关不可恢复。若确定删除协议网关，在弹出窗口中点击删除按钮。

分配运行资源¶

每个协议网关默认分配的运行资源为 1。若需要，可更改分配。

进入 设备接入 > 协议网关，从列表中寻找待分配运行资源的协议网关。
点击 运行配置。注：当协议网关的状态处于 开启中 或 已开启 时不能更改分配。
根据需求编辑 单实例运行资源。
- 单实例运行资源：表示每个协议网关消耗的计算资源（以 CU 计算）。逻辑较复杂的设备协议需要消耗较多计算资源，因此推荐为其分配更多的资源。单实例可分配的最大计算资源为 8 CU。
- 运行资源总数：OU 申请到的协议网关资源总数。
- 剩余资源：可用的剩余资源数。
点击确定以保存修改内容。

开启/关闭协议网关¶

进入 设备接入 > 协议网关，从列表中寻找需要开启/关闭的协议网关，并点击 开启设备网关 或 关闭设备网关 图标。
状态列中的状态将相应更改。
当协议网关成功开启之后，则可以通过网络组件中定义的网络协议发送请求。

备注

点击开启后，等待大约 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=id123456
- securemode=2
- signmethod=sha256
- connect-type=integration
- access-token=44b1d16f9754e739206969b8e2d509bb328b20e2
- protocol-gateway-id=607f884bc6b5090250d87321
- timestamp=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 = id123456
  - deviceKey = dK987654
  - productKey = pK11111
  - timestamp = 1234567890
  则 content= clientIdid123456deviceKeydK987654productKeypK11111timestamp1234567890
- deviceSecret：设备的 device secret。当设备完成创建后，可在 EnOS 管理控制台 上查看该值。
- productSecret：设备的 product secret。当设备完成创建后，可在 EnOS 管理控制台 上查看该值。

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 建立连接。