CreateSubscribeRelation - IoT Platform

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.