HTTP/2轉儲功能適用于生活物聯網平臺與企業服務器之間的消息流轉。通過集成和使用HTTP/2 SDK,即可實現身份認證、消息接收的能力。我們推薦使用HTTP/2的方式推送設備數據(如設備狀態數據、設備控制記錄等),用戶信息數據等。

前提條件

啟動設備數據同步,并配置要同步數據的產品。詳細參見設置數據同步數據同步
說明 當開啟數據同步后,集成HTTP/2客戶端SDK來訂閱數據。如果通過控制臺關閉數據同步再開啟時,客戶端SDK需要重新進行連接流程,否則無法正常接收數據。如果切換不同的HTTP/2客戶端,需要把之前的客戶端斷開,再連接新的客戶端。否則新客戶端無法正常接收數據。

HTTP/2 SDK使用

  1. 引入依賴。
    在項目中添加Maven依賴,Maven信息如下。
    <dependency>
      <groupId>com.aliyun.openservices</groupId>
      <artifactId>iot-client-message</artifactId>
      <version>1.1.5</version>
    </dependency>
    
    <dependency>
        <groupId>commons-codec</groupId>
        <artifactId>commons-codec</artifactId>
        <version>1.11</version>
    </dependency>
                            
  2. 認證身份信息。
    • 身份認證需要使用AppKey和AppSecret,該信息可以從控制臺中獲取。獲取身份信息
    • 認證身份信息需要profile信息,且Profile需要提供EndPoint、AppKey和AppSecret用于鑒權。
      Profile profile = Profile.getAppKeyProfile("${END_POINT}", "${APP_KEY}", "${APP_SECRET}");

      其中,EndPoint是連接節點,具體取值如下表所示。

      區域 End Point
      中國內地 https://ilop.iot-as-http2.cn-shanghai.aliyuncs.com:443
      新加坡 https://ilop.iot-as-http2.ap-southeast-1.aliyuncs.com:443
      美國(弗吉尼亞) https://ilop.iot-as-http2.us-east-1.aliyuncs.com:443
      德國(法蘭克福) https://ilop.iot-as-http2.eu-central-1.aliyuncs.com:443
  3. 接收云端消息。

    首先需要創建消息接收的客戶端對象client,并傳入上面身份認證的profile信息。當消息接收的客戶端和服務端建立連接后,服務端會立即向消息接收的客戶端推送已訂閱的消息,因此建立連接時需要提供默認消息接收的回調接口,用于處理云端推送的消息。

    代碼片段示例如下。

    MessageClient messageClient = MessageClientFactory.messageClient(profile);
    MessageCallback messageCallback = new MessageCallback() {
            public Action consume(MessageToken messageToken) {
                System.out.println("receive : " + new String(messageToken.getMessage().getPayload()));
                return Action.CommitSuccess;
            }
        };
    
    messageClient.connect(messageCallback);
    • 消息接收的回調接口

      用戶需要實現MessageCallback接口的consume方法,并調用客戶端對象client的setMessageListener()方法設置回調接口。

      代碼片段示例如下。

      MessageCallback messageCallback = new MessageCallback() {
          public Action consume(MessageToken messageToken) {
              System.out.println("receive : " + new String(messageToken.getMessage().getPayload()));
              return Action.CommitSuccess;
          }
      };
      
      messageClient.setMessageListener(messageCallback);
    • 指定Topic回調

      對于消息接收的回調接口,可以指定帶通配符的Topic,如/${ProductKey}/{$DeviceName}/#,指定Topic的回調優先級高于通用的回調,一條消息匹配到多個Topic時,按英文字母順序優先調用,僅會回調一次。

      關于topic的概念請參見什么是Topic

      示例如下。

      // 當收到消息的Topic匹配到"/Product_A/Device_B/update"時,會優先調用該回調
      messageClient.setMessageListener("/Product_A/Device_B/#",messageCallback);
    • 通用回調

      設置該回調后,對于未設置指定的topic回調的消息,均會調用該回調。示例如下。

      // 當收到消息的topic未匹配到已指定的Topic時,調用該回調。該通用回調的設置效果等同于messageClient.connect(messageCallback)的。
      messageClient.setMessageListener(messageCallback);

    完整示例如下。

    public static void main(String[] args) throws UnsupportedEncodingException {
        Profile profile = Profile.getAppKeyProfile("要連接的<END_POINT>", "您的<AppKey>", "您的<AppSecret>");
        MessageCallback messageCallback = new MessageCallback() {
            public Action consume(MessageToken messageToken) {
                System.out.println("receive : " + new String(messageToken.getMessage().getPayload()));
                return Action.CommitSuccess;
            }
        };
    
        MessageClient messageClient = MessageClientFactory.messageClient(profile);
        messageClient.setMessageListener(messageCallback);
        messageClient.connect(messageCallback);    
    
        try
        {
            System.in.read();
        } catch (Exception e) {}
    }
    說明 消息推送失敗時,平臺會重新推送,重試策略如下。
    • 如果對端不在線或未回復ack消息,則會造成消息堆積,堆積的消息轉為離線消息。
    • 離線消息每隔5min重試推送一次(每次推送10條)。對端如果成功接收了消息,則重試策略會繼續推送剩余的離線消息(推送失敗的消息,下一次繼續推送)。
    • 離線消息最多會保存7天,如果7天后仍然無法推送成功,則會被刪除。
    • 離線消息會進入單獨的隊列,不會影響后續消息的實時推送。

消息格式

  • 物的屬性變更消息

    topic:/${productKey}/${deviceName}/thing/event/property/post

    消息字段說明如下。

    參數 子參數 子參數 類型 含義
    deviceType String 設備所屬品類
    gmtCreate Long 數據流轉消息產生時間,自1970-1-1起流逝的毫秒值
    iotId String 設備的唯一ID
    productKey String 設備所屬產品的唯一標識符
    deviceName String 設備名稱
    items JSON 變更的狀態列表
    attribute String 發生變更的屬性,具體取值由具體情況確定
    value 具體數據類型由具體情況確定 變更值
    time Long 設備屬性發生變化的時間,自1970-1-1起流逝的毫秒值

    消息示例如下。

    {
        "deviceType": "SmartDoor",
        "iotId": "Xzf15db9xxxxxxxxWR001046b400",
        "productKey": "a17xxxxTYNA",
        "gmtCreate": 153xxxx145304,
        "deviceName": "Xzf15xxxxucTHBgUo6WR",
        "items": {
            "WIFI_Rx_Rate": {
                "value": 74274,
                "time": 1534299145344
            }
        }
    }  
  • 物的事件變更消息

    topic:/${productKey}/${deviceName}/thing/event/{tsl.event.identifier}/post

    消息字段說明如下。

    參數 子參數 類型 含義
    deviceType String 設備所屬品類
    iotId String 設備的唯一ID
    productKey String 設備所屬產品的唯一標識符
    deviceName String 設備名稱
    identifier String 事件標識符,對應事件的identifier
    name String 事件名稱
    type String 事件類型
    time Long 設備上報value對應的時間,自1970-1-1起流逝的毫秒值
    value JSON 變更的事件屬性列表:key-value鍵值對
    key String 屬性key
    value 具體數據類型由具體情況確定 屬性取值

    消息示例如下。

    {
        "deviceType": "SmartDoor",
        "identifier": "Doorxxxxication",
        "iotId": "Xzf15db9xxxxxxxxx01046b400",
        "name": "開門通知",
        "time": 1534319108982,
        "type": "info",
        "productKey": "a17xxxxTYNA",
        "deviceName": "Xzf15xxxxucTHBgUo6WR",
        "value": {
            "KeyID": "x8xxxxxkDY",
            "LockType": 3
        }
    }
  • 設備服務返回消息

    topic:/${productKey}/${deviceName}/thing/downlink/reply/message

    消息字段說明如下。

    參數 類型 含義
    gmtCreate Long 數據流轉消息產生時間,自1970-1-1起流逝的毫秒值
    iotId String 設備的唯一ID
    productKey String 設備所屬產品的唯一標識符
    deviceName String 設備名稱
    requestId String 阿里云產生和設備通信的信息ID
    code Integer 調用的結果信息
    message String 結果信息說明
    topic String 服務調用下行時使用的topic
    data Object 設備返回的結果,非透傳之間返回設備結果,透傳則需要經過腳本轉換

    消息示例如下。

    {
      "gmtCreate": 151xxxx39881,
      "iotId": "4z819VQHxxxxxxxxxxxx7ee200",
      "productKey": "p1gxxxxBd",
      "deviceName": "xxxxxxxxxx",
      "requestId": "1234",
      "code": 200,
      "message": "success",
      "topic": "/sys/p1gsv0teUBd/xxxxxxxxxx/thing/service/property/set",
      "data": {}
    }           
  • 物的狀態變更消息

    為了提高消息有效性,設備上下線過于頻繁時,會對消息進行篩檢。

    topic: /${productKey}/${deviceName}/mqtt/status

    消息字段說明如下。

    參數 子參數 類型 含義
    deviceType String 設備所屬品類
    gmtCreate Long 數據流轉消息產生時間,自1970-1-1起流逝的毫秒值
    iotId String 設備的唯一ID
    action String 設備狀態變更動作:
    • online:上線動作
    • offline:下線動作
    productKey String 設備所屬產品的唯一標識符
    deviceName String 設備名稱
    status JSON 狀態信息,元素包括:value-狀態值,time-發生變化的時間
    time Long 設備上下線狀態發生變化的時間,自1970-1-1起流逝的毫秒值
    value String 設備上下線狀態

    value狀態值定義:

    • 1:在線
    • 0:離線

    消息示例如下。

    {
        "deviceType": "SmartDoor",
        "iotId": "Xzf15dxxxxxxxxxxxxxxxx01046b400",
        "action": "online",
        "productKey": "a17xxxxxxTYNA",
        "gmtCreate": 153xxxx1368,
        "deviceName": "Xzf1xxxxxxxxxxxxgUo6WR",
        "status": {
            "time": 1534319611368,
            "value": "1"
        }
    }       
  • 用戶綁定變更消息

    用戶綁定/解綁設備產生的回流消息,用于同步用戶與設備的綁定、解綁。

    topic:/${productKey}/${deviceName}/thing/awss/enrollee/user

    消息字段說明如下。

    參數 子參數 類型 含義
    bind bool true-綁定;false-解綁
    productKey String 設備所屬產品的唯一標識符
    deviceName String 設備名稱
    iotId String 設備的唯一ID
    messageCreateTime JSON 消息創建時間
    identityInfos list 用戶信息列表
    identityId String 用戶身份ID
    scopeId String 隔離ID
    tenantId String 租戶ID
    owned Integer 擁有標記
    • 0:分享者
    • 1:擁有者
    params Map 擴展參數(暫未使用)
    {
      "bind":true,
      "productKey": "123xxxx569",
      "deviceName": "deviceNamexxxx34",
      "iotId": "",
      "messageCreateTime": 151xxxx9881,
      "identityInfos":[
         {
           "identityId":"50xxxxxxxxxxxx62060259",
           "scopeId":"",
           "tenantId":"1D89B5xxxxxxxxxxxxxxxx861678FF",
           "owned":1
         }
      ],
      "params":{
      }
    }