全部產品
Search

搜尋本產品

    IoT Platform：CreateSubscribeRelation

    文件中心

    IoT Platform：CreateSubscribeRelation

    更新時間：Feb 13, 2025

    調用該介面建立MNS或AMQP服務端訂閱。

    使用說明

    服務端訂閱分兩種類型：

    • MNS訂閱：將訂閱的訊息推送到Message Service（MNS）的隊列中，您的服務端應用通過監聽MNS隊列接收裝置訊息，參見使用MNS服務端訂閱。直接調用本介面即可建立MNS訂閱。

    • AMQP訂閱：將產品下所有已訂閱類型的訊息通過AMQP通道推送至您的服務端，請參見配置AMQP服務端訂閱。請按以下流程操作AMQP訂閱：

      1. 調用CreateConsumerGroup建立消費組，返回消費組ID。AMQP訂閱中，訊息將被推送到指定消費組，AMQP用戶端攜帶消費組ID接入物聯網平台，消費訊息，請參見AMQP用戶端接入說明。

      2. 調用本介面建立AMQP訂閱。

      3. （可選）調用CreateConsumerGroupSubscribeRelation在AMQP訂閱中添加消費組。調用DeleteConsumerGroupSubscribeRelation刪除AMQP訂閱中多個消費組中的指定消費組。

      4. （可選）運行AMQP訂閱時，調用QueryConsumerGroupStatus查詢某個消費組的狀態，包括線上用戶端資訊、訊息消費速率、訊息堆積數、最近訊息消費時間，調用ResetConsumerGroupPosition清空消費組的堆積訊息。

    QPS限制

    單個阿里雲帳號調用該介面的每秒請求數（QPS）最大限制為5。

    說明 RAM使用者共用阿里雲帳號配額。

    調試

    您可以在OpenAPI Explorer中直接運行該介面，免去您計算簽名的困擾。運行成功後，OpenAPI Explorer可以自動產生SDK程式碼範例。

    請求參數

    名稱 類型 是否必選 樣本值 描述
    Action String 是 CreateSubscribeRelation

    系統規定參數。取值：CreateSubscribeRelation。
    ProductKey String 是 a1fyXVF****

    該訂閱中的產品的ProductKey。
    IotInstanceId String 否 iot-cn-0pp1n8t****

    執行個體ID。您可在物聯網平台控制台的執行個體概覽頁面，查看當前執行個體的ID。

    重要
    • 若有ID值，必須傳入該ID值，否則調用會失敗。
    • 若無執行個體概覽頁面或ID值，則無需傳入。

    執行個體的更多資訊，請參見執行個體概述。
    DeviceDataFlag Boolean 否 true

    推送訊息類型是否選擇裝置上報訊息。可選值：

    • true：是。
    • false（預設）：否。
    DeviceStatusChangeFlag Boolean 否 true

    推送訊息類型是否選擇裝置狀態變化通知。可選值：

    • true：是。
    • false（預設）：否。
    DeviceTopoLifeCycleFlag Boolean 否 true

    推送訊息類型是否選擇裝置拓撲關係變更。可選值：

    • true：是。僅對網關產品有效。
    • false（預設）：否。
    FoundDeviceListFlag Boolean 否 true

    推送訊息類型是否選擇網關子裝置發現上報。可選值：

    • true：是。僅對網關產品有效。
    • false（預設）：否。
    ThingHistoryFlag Boolean 否 true

    推送訊息類型是否選擇物模型歷史資料上報。可選值：

    • true：是。
    • false（預設）：否。
    DeviceLifeCycleFlag Boolean 否 true

    推送訊息類型是否選擇裝置生命週期變更。可選值：

    • true：是。
    • false（預設）：否。
    OtaEventFlag Boolean 否 true

    推送訊息類型是否選擇OTA升級狀態通知。可選值：

    • true：是。
    • false（預設）：否。
    DeviceTagFlag Boolean 否 true

    推送訊息類型是否選擇裝置標籤變更。可選值：

    • true：是。僅當Type為AMQP時有效。
    • false（預設）：否。
    OtaVersionFlag Boolean 否 true

    推送訊息類型是否選擇OTA模組版本號碼上報。可選值：

    • true：是。僅當Type為AMQP時有效。
    • false（預設）：否。
    OtaJobFlag Boolean 否 true

    推送訊息類型是否選擇OTA升級批次狀態通知。可選值：

    • true：是。僅當Type為AMQP時有效。
    • false（預設）：否。
    Type String 否 AMQP

    訂閱類型：

    • MNS。
    • AMQP。
    ConsumerGroupIds.N RepeatList 否 nJRaJPn5U1JITGfjBO9l00****

    建立的AMQP訂閱中的消費組ID，Type為AMQP時必填。

    調用CreateConsumerGroup建立消費組成功後，會返回消費組ID。您可以調用QueryConsumerGroupList按消費組名稱查詢消費組ID，也可以在物聯網平台控制台，選擇訊息轉寄>服務端訂閱>消費組列表，查看消費組ID。
    MnsConfiguration String 否 { "queueName": "mns-test-topic1", "regionName": "cn-shanghai", "role": { "roleArn": "acs:ram::5645***:role/aliyuniotaccessingmnsrole", "roleName": "AliyunIOTAccessingMNSRole" } }

    MNS隊列的配置資訊，Type為MNS時必填。

    具體要求和樣本見下文“MnsConfiguration定義”。
    SubscribeFlags String 否 { "jt808DeviceDataFlag": true }

    標識當前訂閱產品的其他類型訊息。

    如果訂閱的是JT/T 808協議雲網關產品，必須傳入SubscribeFlags，取固定值為：

    
{
    "jt808DeviceDataFlag": true
}
    說明 請求參數中的Flag不能全部為false或不傳入，至少傳入一個為true的Flag。
    MnsConfiguration定義

    名稱

    描述

    queueName

    Message Service中用來接收資訊的隊列名稱。您需先在Message ServiceMNS控制台，建立隊列，擷取隊列名稱。具體操作，請參見建立隊列。

    regionName

    目標Message Service所在的阿里雲地區代碼，例如cn-shanghai。

    role

    授權角色資訊。通過授予物聯網平台指定的系統服務角色，您可以授權物聯網平台訪問您的Message Service。授權角色資訊如下：

    {"roleArn":"acs:ram::5645***:role/aliyuniotaccessingmnsrole","roleName": "AliyunIOTAccessingMNSRole"}

    請將5645***替換成您的阿里雲帳號ID。您可以登入控制台，在帳號安全設定頁面查看您的帳號ID。

    AliyunIOTAccessingMNSRole是存取控制中定義的服務角色。用於授予物聯網平台訪問Message Service。關於角色的更多資訊，請在存取控制RAM控制台的角色管理頁面進行角色管理。

    MnsConfiguration樣本：

    
{
    "queueName": "mns-test-topic1",
    "regionName": "cn-shanghai",
    "role": {
        "roleArn": "acs:ram::5645***:role/aliyuniotaccessingmnsrole",
        "roleName": "AliyunIOTAccessingMNSRole"
    }
}

    調用API時，除了本文介紹的該API的特有請求參數，還需傳入公用請求參數。公用請求參數說明，請參見公用參數文檔。

    返回資料

    名稱 類型 樣本值 描述
    Code String iot.system.SystemException

    調用失敗時，返回的錯誤碼。更多資訊，請參見錯誤碼。
    ErrorMessage String 系統異常

    調用失敗時，返回的出錯資訊。
    RequestId String 21D327AF-A7DE-4E59-B5D1-ACAC8C024555

    阿里雲為該請求產生的唯一識別碼。
    Success Boolean true

    是否調用成功。

    • true：調用成功。
    • false：調用失敗。

    樣本

    請求樣本

    https://iot.cn-shanghai.aliyuncs.com/?Action=CreateSubscribeRelation
&OtaEventFlag=true
&ProductKey=a1Zkii7****
&Type=AMQP
&ConsumerGroupIds.1=Xs95KifeaSKbi8tKkcoD00****
&<公用請求參數>

    正常返回樣本

    XML格式

    <CreateSubscribeRelationResponse>
        <RequestId>C21DA94F-07D7-482F-8A0C-5BB0E3CC1A82</RequestId>
        <Success>true</Success>
</CreateSubscribeRelationResponse>

    JSON格式

    {
    "RequestId": "C21DA94F-07D7-482F-8A0C-5BB0E3CC1A82",
    "Success": true
}

    錯誤碼

    訪問錯誤中心查看更多錯誤碼。