开发指南（.NET）

配置服务端订阅

在物联网平台控制台配置要订阅的消息类型。

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());

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

设置消息接收接口

连接建立后，服务端会立即向 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，参数为 topic、messageId和连接体。 这些参数可以在接收消息中获取到。

    手动回复 ACK 的方法：

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

相关文档

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