本文档为服务端订阅功能的开发指南,介绍了.NET版本的开发方法。完成后,您可以成功使用SDK,通过HTTP/2通道,接收物联网平台推送过来的设备消息.

服务端订阅Demo:HTTP/2 SDK(.NET) server side demo
说明
  • 使用Demo程序时,需要使用NLog包。请访问NLog官网下载,建议版本号:4.5.11。
  • 使用Demo程序时,请引入最新依赖包。使用依赖包时,需引入Newtonsoft.Json,建议版本号:12.0.2 。

以下简单介绍服务端订阅的开发流程。

配置服务端订阅

  1. 登录物联网平台控制台
  2. 左侧导航栏选择设备管理 > 产品
  3. 在产品列表中,搜索到要配置服务端订阅的产品,并单击该产品对应的查看按钮,进入产品详情页。
  4. 单击服务端订阅 > 设置
  5. 选择推送的消息类型。


    • 设备上报消息:指产品下所有设备 Topic 列表中,具有发布权限的 Topic 中的消息。勾选后,可以通过 HTTP/2 SDK 接收这些消息。

      设备上报消息,包括设备上报的自定义数据和物模型数据(属性上报、事件上报、属性设置响应和服务调用响应)。

      例如,一个产品有3个Topic类,分别是:
      • /${YourProductKey}/${YourDeviceName}/user/get,具有订阅权限。
      • /${YourProductKey}/${YourDeviceName}/user/update,具有发布权限。
      • /sys/${YourProductKey}/${YourDeviceName}/thing/event/property/post,具有发布权限。

      那么,服务端订阅会推送具有发布权限的Topic类中的消息,即/${YourProductKey}/${YourDeviceName}/user/update和/sys/${YourProductKey}/${YourDeviceName}/thing/event/property/post中的消息。其中,/sys/${YourProductKey}/${YourDeviceName}/thing/event/property/post中的数据已经过系统处理。

    • 设备状态变化通知:指一旦该产品下的设备状态变化时通知的消息,例如设备上线、下线的消息。设备状态消息的发送 Topic 为/as/mqtt/status/${YourProductKey}/${YourDeviceName} 。勾选后,可以通过 HTTP/2 SDK 接收设备状态变化的通知消息。
    • 网关发现子设备上报:网关可以将发现的子设备信息上报给物联网平台。需要网关上的应用程序支持。网关产品特有消息类型。
    • 设备拓扑关系变更:子设备和网关之间的拓扑关系建立和解除消息。网关产品特有消息类型。
    • 设备生命周期变更:设备创建、删除、禁用、启用等消息。
说明 设备上报物模型消息、设备状态变化通知、网关发现子设备上报消息、设备拓扑关系变更消息和设备生命周期变更消息均默认为QoS=0;设备上报消息(除物模型相关消息外),您可以在设备端上设置为QoS=0或QoS=1。

接入 SDK

在工程中添加依赖包

身份认证

使用服务端订阅功能,需要基于您的阿里云 AccessKey 进行身份认证并建立连接。

建立连接示例如下:

//阿里云accessKey
string accessKey = "xxxxxxxxxxxxxxx";
//阿里云accessSecret
string accessSecret = "xxxxxxxxxxxxxxx";
//regionId
string regionId = "cn-shanghai";
//阿里云uid
string uid = "xxxxxxxxxxxxxxx";
//domain
string domain = ".aliyuncs.com";
//endpoint
string endpoint = "https://" + uid + ".iot-as-http2." + regionId + domain;

//连接参数配置
Profile profile = new Profile();
profile.AccessKey = accessKey;
profile.AccessSecret = accessSecret;
profile.RegionId = regionId;
profile.Domain = domain;
profile.Url = endpoint;
//清除堆积消息
profile.CleanSession = true;
profile.GetAccessKeyAuthParams();

//构造客户端
IMessageClient client = new MessageClient(profile);

//连接HTTP2通道,并接收消息
client.DoConnection(new DefaultHttp2MessageCallback());

//指定topic回调
client.SetMessageListener("/${YourProductKey}/#", new CustomHttp2MessageCallback());

以上示例中账号相关信息的获取方法:

参数 获取途径
accessKey 您的账号AccessKey ID。

登录阿里云控制台,将光标移至账号头像上,然后单击accesskeys,跳转至用户信息管理页,即可获取。

accessSecret 您的账号AccessKey Secret。获取方式同accessKey。
uid 您的账号ID。

用主账号登录阿里云控制台,单击账号头像,跳转至账号管理控制台,即可获取账号UID。

regionId 您的物联网平台服务所在地域代码。

在物联网平台控制台页,右上方即可查看地域(Region)。RegionId 的表达方法,请参见文档地域和可用区

设置消息接收接口

连接建立后,服务端会立即向 SDK 推送已订阅的消息。因此,建立连接时,需要实现消息接收接口。

消息接收接口如下:
public interface IHttp2MessageCallback
{
    ConsumeAction Consume(Http2ConsumeMessage http2ConsumeMessage);
}

您需要通过 IHttp2MessageCallback接口的consume方法,来设置消息接收接口。

设置消息接收接口的方法如下:

public class DefaultHttp2MessageCallback : IHttp2MessageCallback
    {
        public DefaultHttp2MessageCallback()
        {
        }

        public ConsumeAction Consume(Http2ConsumeMessage http2ConsumeMessage)
        {
            Console.WriteLine("receive : " + http2ConsumeMessage.MessageId);
            //自动回复ACK
            return ConsumeAction.CommitSuccess;
        }
    }

其中,

  • 参数 Http2ConsumeMessage 是消息回执的消息体。

    消息体包含的内容如下:

    public class Http2ConsumeMessage
    {
        //消息体
        public byte[] Payload { get; set; }
        //Topic
        public string Topic { get; set; }
        //消息ID
        public string MessageId { get; set; }
        //QoS
        public int Qos { get; set; }
        //连接体
        public Http2Connection Connection { get; set; }
    }

    各类型消息具体格式,请参见数据格式

    说明 关于设备上下线状态,为避免消息时序紊乱造成影响,建议您根据消息中的lastTime字段来判断最终设备状态。
  • messageClient.setMessageListener("/${YourProductKey}/#",messageCallback);用于设置回调。本示例中,设置为指定 Topic 回调。

    您可以设置为指定 Topic 回调,也可以设置为通用回调。

    • 指定 Topic 回调

      指定 Topic 回调的优先级高于通用回调。一条消息匹配到多个 Topic 时,按字典顺序优先调用,并且仅回调一次。

      设置回调时,可以指定带通配符的 Topic,如/${YourProductKey}/${YourDeviceName}/# 。

      示例:
      client.SetMessageListener("/alEddfaXXXX/device1/#",messageCallback);
      //当收到消息的Topic,如"/alEddfaXXXX/device1/update",匹配指定Topic时,会优先调用该回调
    • 通用回调

      未指定 Topic 回调的消息,则调用通用回调。

      设置通用回调方法:
      new DefaultHttp2MessageCallback()
  • 设置回复 ACK(acknowledgement,即回复确认消息)。

    对于 QOS>0 的消息,消费后需要回复 ACK。SDK 支持自动回复 ACK 和手动回复 ACK。默认为自动回复 ACK。本示例中未设置回复 ACK,则默认为自动回复。

    • 自动回复 ACK:设置为自动回复 ACK 后,若 IHttp2MessageCallback.consume的返回值为 ConsumeAction.CommitSuccess 则 SDK 会发送 ACK;返回 ConsumeAction.CommitFailure 或抛出异常,则不会返回 ACK。对于 QOS>0 且未回复 ACK 的消息,服务端会重新发送。
    • 手动回复 ACK:通过ConsumeAction.CommitFailure设置手动回复 ACK。

      设置为手动回复 ACK 后,需要调用MessageClient.DoAck()方法回复 ACK,参数为 topicmessageId和连接体。 这些参数可以在接收消息中获取到。

      手动回复 ACK 的方法:

      client.DoAck(connection, topic, messageId, delegate);

相关文档

  • 服务端订阅使用限制说明,请参见使用限制
  • 查看各类型消息的具体格式,请参见数据格式