Creates a Message Service (MNS) or Advanced Message Queuing Protocol (AMQP) server-side subscription.

Usage notes

Server-side subscriptions are categorized into the following two types:

  • MNS subscription: pushes subscribed messages to MNS queues. Your server applications listen to MNS queues to receive device messages. For more information, see Configure MNS server-side subscriptions. You can call this operation to create an MNS subscription.

  • AMQP subscription: pushes subscribed messages to your server by using the AMQP channel. For more information, see Configure AMQP server-side subscriptions. To configure an AMQP subscription, perform the following steps:

    1. Call the CreateConsumerGroup operation to create a consumer group and obtain the returned consumer group ID. Messages are pushed to the consumer group. The AMQP client carries the consumer group ID when the client connected to IoT Platform. For more information, see Connect an AMQP client to IoT Platform.

    2. Call the CreateSubscribeRelation operation to create an AMQP subscription.

    3. Optional. Call the CreateConsumerGroupSubscribeRelation operation to add a consumer group to the AMQP subscription. You can also call the DeleteConsumerGroupSubscribeRelation operation to remove a consumer group from an AMQP subscription.

    4. Optional. Call the QueryConsumerGroupStatus operation to query the status of a consumer group, including online client information, message consumption rate, number of accumulated messages, and last message consumption time. You can also call the ResetConsumerGroupPosition operation to clear the accumulated messages of the consumer group.

QPS limits

You can call this API operation up to five times per second per account.

Note The RAM users of an Alibaba Cloud account share the quota of the account.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String Yes CreateSubscribeRelation

The operation that you want to perform. Set the value to CreateSubscribeRelation.

ProductKey String Yes a1fyXVF****

The ProductKey of the product that is specified for the subscription.

IotInstanceId String No iot-cn-0pp1n8t****

The ID of the instance. You can view the ID of the instance on the Overview page in the IoT Platform console.

Important
  • If your instance has an ID, you must specify the ID for this parameter. Otherwise, the call fails.
  • If no Overview page or ID is generated for your instance, you do not need to configure this parameter.

For more information, see Overview.

DeviceDataFlag Boolean No true

Specifies whether to push upstream device messages. Valid values:

  • true: yes.
  • false: no. This is the default value.
DeviceStatusChangeFlag Boolean No true

Specifies whether to push messages about device status changes. Valid values:

  • true: yes.
  • false: no. This is the default value.
DeviceTopoLifeCycleFlag Boolean No true

Specifies whether to push messages about topological relationship changes of devices. Valid values:

  • true: yes. This parameter is valid only for gateway products.
  • false: no. This is the default value.
FoundDeviceListFlag Boolean No true

Specifies whether to push messages when a gateway detects new sub-devices. Valid values:

  • true: yes. This parameter is valid only for gateway products.
  • false: no. This is the default value.
ThingHistoryFlag Boolean No true

Specifies whether to push upstream historical Thing Specification Language (TSL) data. Valid values:

  • true: yes.
  • false: no. This is the default value.
DeviceLifeCycleFlag Boolean No true

Specifies whether to push messages about device lifecycle changes. Valid values:

  • true: yes.
  • false: no. This is the default value.
OtaEventFlag Boolean No true

Specifies whether to push notifications about the status of over-the-air (OTA) update batches. Valid values:

  • true: yes.
  • false: no. This is the default value.
DeviceTagFlag Boolean No true

Specifies whether to push messages about device tag changes. Valid values:

  • true: yes. This parameter is valid only if you set the Type parameter to AMQP.
  • false: no. This is the default value.
OtaVersionFlag Boolean No true

Specifies whether to push messages about the version numbers of OTA modules. Valid values:

  • true: yes. This parameter is valid only if you set the Type parameter to AMQP.
  • false: no. This is the default value.
OtaJobFlag Boolean No true

Specifies whether to push notifications about the status of OTA update batches. Valid values:

  • true: yes. This parameter is valid only if you set the Type parameter to AMQP.
  • false: no. This is the default value.
Type String No AMQP

The type of the subscription. Valid values:

  • MNS
  • AMQP
ConsumerGroupIds.N RepeatList No nJRaJPn5U1JITGfjBO9l00****

The IDs of the consumer groups that are created in the AMQP subscription. This parameter is required if you set the Type parameter to AMQP.

After you call the CreateConsumerGroup operation to create a consumer group, the consumer group ID is returned. You can call the QueryConsumerGroupList operation to query consumer group IDs by consumer group name. You can also log on to the IoT Platform console and choose Message Forwarding > Server-side Subscription > Consumer Groups to view the consumer group ID.

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

The configurations of the MNS queue. If you set the Type parameter to AMQP, this parameter is required.

For more information, see the "Definition of the MnsConfiguration parameter" section.

SubscribeFlags String No { "jt808DeviceDataFlag": true }

Specifies whether to receive the messages of a specific subscribed product.

If you subscribe to JT/T 808 gateway products, you must configure the SubscribeFlags parameter. Set the value to the following code.


{
    "jt808DeviceDataFlag": true
}
Note You must set at least one Flag-related parameter to true.
Definition of the MnsConfiguration parameter

Parameter

Description

queueName

The name of the MNS topic that is used to receive data. You must create a queue in the MNS console and obtain the queue name. For more information, see Create a queue.

regionName

The code of the region where MNS is deployed. Example: cn-shanghai.

role

The information about the RAM role. To authorize IoT Platform to access MNS, you can assign a service role to IoT Platform. The following script shows the syntax of a RAM role:

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

Replace 5645*** with your Alibaba Cloud account ID. You can log on to the Alibaba Cloud Management Console and view the account ID on the Security Settings page.

AliyunIOTAccessingMNSRole indicates a service-linked role that is defined in Resource Access Management (RAM). This role is used to authorize IoT Platform to access MNS. You can go to the RAM Roles page of the RAM console to manage RAM roles.

Example of the MnsConfiguration parameter


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

In addition to the preceding operation-specific request parameters, you must configure common request parameters when you call this operation. For more information about common request parameters, see Common parameters.

Response parameters

Parameter Type Example Description
Code String iot.system.SystemException

The error code that is returned if the call fails. For more information about error codes, see Error codes.

ErrorMessage String A system exception occurred.

The error message returned if the call fails.

RequestId String 21D327AF-A7DE-4E59-B5D1-ACAC8C024555

The ID of the request.

Success Boolean true

Indicates whether the call was successful. Valid values:

  • true: The call was successful.
  • false: The call failed.

Examples

Sample requests

https://iot.cn-shanghai.aliyuncs.com/?Action=CreateSubscribeRelation
&OtaEventFlag=true
&ProductKey=a1Zkii7****
&Type=AMQP
&ConsumerGroupIds.1=Xs95KifeaSKbi8tKkcoD00****
&<Common request parameters>

Sample success responses

XML format

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

JSON format

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

Error codes

For a list of error codes, see Service error codes.