若您使用MQTT云网关将设备接入物联网平台,需通过添加云网关创建对应产品。本文介绍添加MQTT协议云网关的具体步骤。
前提条件
已购买尊享型企业版实例。购买方法,请参见购买企业版实例。
背景信息
物联网平台的云网关使用说明,请参见接入MQTT云网关设备。
添加云网关
登录物联网平台控制台。
在实例概览页面,单击目标尊享型实例。
在左侧导航栏,选择 ,单击添加云网关。
配置基本信息,然后单击下一步。
参数
说明
云网关名称
为云网关命名。名称在实例内需具有唯一性。支持中文、英文字母、日文、数字、下划线(_),长度限制4~30个字符,一个中文或日文占2个字符。
协议
选择MQTT。
自定义端口号
取值范围为1024~65535。默认端口号为1883。
是否开启数据解析
选择云网关设备是否开启数据解析功能。
物联网平台透传云网关设备数据,您可根据实际业务需要,开启数据解析功能。您可在数据解析脚本中实现
transformPayload()
方法,将设备上报的原始数据转换为标准的JSON格式或物模型的Alink协议格式。数据解析功能的详细说明,请参见什么是消息解析。认证类型
一方认证
您需要将设备认证信息(UserName、Password、SN)导入物联网平台,物联网平台会基于设备认证信息对设备进行认证。
三方认证
您需要选择阿里云函数计算或外部HTTPS认证方式。阿里云函数计算FC的更多信息,请参见什么是函数计算。
阿里云FC:需设置设备认证FC服务、设备认证FC函数和授权,您可以选择已有的FC函数或创建新的FC函数FC认证函数的入参、出参需要符合规范,认证函数名称可以自定义。认证函数的入参、出参说明,请参见表 1. FC认证函数说明。
外部HTTPS:必须配置设备认证HTTPS URL,可以配置自定义认证参数。
设备认证URL以
https://
开头。物联网平台通过HTTPS方式调用自定义的设备认证服务,实现HTTPS调用的入参、出参需要符合规范。具体说明,请参见表 2. HTTPS认证参数说明。最多配置10个自定义认证参数(
Key:Value
)。参数Key:参数名称,长度不可超过64个字符。
参数Value:参数值,长度不可超过64个字符。支持设置为变量,变量格式为
${变量名名称}
。支持的变量为:${username}
:设备建连时上传MQTT的userName。${password}
:设备建连时上传MQTT的password${clientId}
:设备建连时上传的MQTT的Client ID信息${cert.***}
:证书信息,其中***
可取值cn
、serial
、issuer
。${userProperties.***}
:Connect报文中的自定义数据UserProperty
,***
为自定义字段标识符。
是否开启设备X.509证书认证
开启设备X.509证书认证
需要配置是否开启OCSP:
不开启
服务端证书的OCSP验证
客户端证书的OCSP验证
客户端+服务端证书的OCSP验证
说明OCSP表示在线证书状态协议,该协议用于向签发证书的CA(Certificate Authority)中心发起查询请求,检查证书是否被吊销。
客户端证书的OCSP校验是在客户端发送消息时执行,如果证书已经吊销,服务端会主动关闭连接。
服务端OCSP Stapling功能默认缓存时间是5分钟至60分钟之间,缓存过期后第一个访问请求OCSP Stapling将不生效,直到重新获取OCSP Stapling信息为止。
不开启设备X.509证书认证
需要配置是否开启OCSP:
不开启
服务端证书的OCSP验证
说明OCSP表示在线证书状态协议,该协议用于向签发证书的CA(Certificate Authority)中心发起查询请求,检查证书是否被吊销。
客户端证书的OCSP校验是在客户端发送消息时执行,如果证书已经吊销,服务端会主动关闭连接。
服务端OCSP Stapling功能默认缓存时间是5分钟至60分钟之间,缓存过期后第一个访问请求OCSP Stapling将不生效,直到重新获取OCSP Stapling信息为止。
表 1. FC认证函数说明
参数类型
参数名称
数据类型
是否必选
描述
请求参数
userName
String
是
设备建连时上传MQTT的userName。
userName支持英文字母、数字、短划线(-)、下划线(_)、at(@)、英文句号(.)和英文冒号(:),长度限制为4~32个字符。userName在产品维度下不可重复。
password
String
是
设备建连时上传MQTT的password。
password支持英文字母、数字、短划线(-)、下划线(_)、at(@)、英文句号(.)和英文冒号(:),长度限制为1~32个字符。
clientId
String
是
设备建连时上传的MQTT的Client ID信息。
certificateCommonName
String
否
该参数为X.509证书规范中的commonName字段。使用X.509数字证书进行设备身份认证时,需上传该参数。
返回参数
result
String
是
认证是否成功,true表示成功,false表示失败。
message
String
否
认证失败时返回的错误信息。
deviceName
String
否
认证成功时,userName对应的设备名称。
设备首次建连时,物联网平台会根据deviceName返回值自动创建对应的设备。
FC认证函数返回参数示例:
{ "result":"true", "deviceName":"device_TH", "message":"" }
表 2. HTTPS认证参数说明
参数类型
参数名称
数据类型
是否必选
描述
示例
请求方法
Method
String
是
请求方法取值POST。
POST Content-Type: application/json body:{ "username": "UN001", "password": "PW001", "certificateCommonName": "CN001" }
Header
Content-Type
String
是
HTTPS Header中定义数据的编码格式,目前只支持
application/json
。若使用其他编码格式,会返回参数错误。
请求参数Body
username
String
是
设备建连时上传MQTT的username。
username支持英文字母、数字、短划线(-)、下划线(_)、at(@)、英文句号(.)和英文冒号(:),长度限制为4~32个字符。username在产品维度下不可重复。
password
String
是
设备建连时上传MQTT的password。
password支持英文字母、数字、短划线(-)、下划线(_)、at(@)、英文句号(.)和英文冒号(:),长度限制为1~32个字符。
certificateCommonName
String
否
该参数为X.509证书规范中的commonName字段。使用X.509数字证书进行设备身份认证时,需上传该参数。
返回参数Body
deviceName
String
是
认证成功时,username对应的设备名称。
设备首次建连时,物联网平台会根据devicename返回值自动创建对应的设备。
body:{ "deviceName": "device_TH" }
完成证书配置,单击完成。
重要物联网平台目前支持RSA、ECC和SM2、SM3、SM4国密算法的私有CA。
使用阿里云PCA服务
重要如果在上一步骤中开启OSCP,无法使用阿里云PCA服务,只能手动输入证书。
使用已有的PCA或创建新的PCA。PCA(Private Certificate Authority,即私有CA)服务的更多信息,请参见私有证书概述。
必须配置服务端证书和服务端证书私钥。
如果开启设备X.509证书认证,还需要配置设备端证书。
如果OCSP认证方式为服务端证书的OCSP验证或客户端+服务端证书的OCSP验证,信任证书默认为服务端的根证书。
手动输入
您可以使用自行签发的CA证书。签发自定义证书的方法,请参见签发自定义证书。
重要以下配置的证书都为PEM格式。
配置服务端证书和服务端证书私钥。
如果开启设备X.509证书认证,还需要配置设备端根证书。
如果OCSP认证方式为服务端证书的OCSP验证或客户端+服务端证书的OCSP验证,信任证书默认为服务端的根证书。
在云网关列表,查看云网关信息,包含云网关名称、云网关ID、网关URL、状态和关联产品等。
重要您需保存云网关URL,对应设备连接物联网平台的MQTT接入域名需替换为该云网关URL。您可直接配置云网关URL为新接入域名,也可配置CNAME将接入域名解析到该云网关URL。
可选:编辑云网关
创建云网关成功后,在云网关列表,找到对应云网关,单击右侧操作栏的编辑,修改云网关名称、证书信息、FC认证函数。
执行结果
创建云网关成功后,物联网平台会自动为云网关创建并关联一个对应的产品,产品名称为云网关+${云网关实例ID}
。您可在 页面,查看新建的产品。
您可单击产品列表右侧操作栏的查看,在产品详情页面查看产品信息,默认配置如下图所示。
后续步骤
三方认证的云网关创建成功后,设备首次建连时,物联网平台会根据三方认证服务的返回参数deviceName值自动创建对应的设备。
您可使用MQTT.fx工具模拟云网关设备接入物联网平台进行通信。具体操作,请参见设备使用MQTT.fx接入(阿里云FC认证)。
一方认证的云网关创建成功后,需您在物联网平台导入设备认证信息来创建云网关设备。具体操作,请参见批量添加设备。