Creates a data destination to which you want to forward data.

QPS limits

Each Alibaba Cloud account can run up to 10 queries per second (QPS).

Note The RAM users of an Alibaba Cloud account share the quota of the Alibaba Cloud 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 of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String Yes CreateDestination

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

Name String Yes DataPurpose

The name of the data destination.

Type String Yes REPUBLISH

The operation that you want to perform on the data of the data destination. Valid values:

  • REPUBLISH: forwards the topic data that is processed by a parser script to an IoT Platform communication topic.
  • AMQP: forwards the topic data that is processed by a parser script to an Advanced Message Queuing Protocol (AMQP) consumer group.
  • DATAHUB: forwards the topic data that is processed by a parser script to Alibaba Cloud DataHub for stream computing.
  • ONS: forwards the topic data that is processed by a parser script to Message Queue for Apache RocketMQ for message distribution.
  • MNS: forwards the topic data that is processed by a parser script to Message Service (MNS) for message transmission.
  • FC: forwards the topic data that is processed by a parser script to Function Compute for event computing.
  • OTS: forwards the topic data that is processed by a parser script to Tablestore (OTS) for NoSQL data storage.
Configuration String Yes {"topic":"/a1POX0c****/device1/user/get","topicType":1}

The configurations of the data destination. Set the value to a JSON string. The configurations vary based on the type of rule actions. The following tables describe the required syntax and relevant examples.

IotInstanceId String No iot-2w****

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

Notice
  • 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.

Description String No The data that you want to forward to a database.

Enter a description of the data destination.

The configurations of the REPUBLISH type

Parameter

Description

productKey

The ProductKey of the product to which the destination topic belongs.

Examples 


{
    "productKey":"hf****3xn"
}
The configurations of the AMQP type

Parameter

Description

groupId

The ID of the consumer group.

Example


{
    "groupId":"ZTh1JmuZcUfv44p4z00****"
}
The configurations of the OTS type

Parameter

Description

instanceName

The name of the Tablestore instance that you want to use to receive data.

regionName

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

tableName

The name of the table that you want to use to receive data.

role

The information about the RAM role. You can grant IoT Platform the access to Tablestore by assigning a service role to IoT Platform. The syntax of a RAM role:

{"roleName":"AliyunIOTAccessingOTSRole","roleArn":"acs:ram::${uid}:role/aliyuniotaccessingotsrole"}

${uid} specifies the ID of your Alibaba Cloud account. You can log on to the Alibaba Cloud Management Console and view the account ID on the Security Settings page.

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

Example


{
    "instanceName":"${instanceName}",
    "regionName":"cn-shanghai",
    "tableName":"test_table",
    "role":{
        "roleName":"AliyunIOTAccessingOTSRole",
        "roleArn":"acs:ram::${uid}:role/aliyuniotaccessingotsrole"
    }
}
The configurations of the DATAHUB type

Parameter

Description

projectName

The name of the DataHub project that you want to use to receive data.

topicName

The name of the DataHub topic that you want to use to receive data.

regionName

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

role

The information about the RAM role. You can grant IoT Platform the access to DataHub by assigning a service role to IoT Platform. The syntax of a RAM role:

{"roleArn":"acs:ram::${uid}:role/aliyuniotaccessingdatahubrole","roleName": "AliyunIOTAccessingDataHubRole"}

${uid} specifies the ID of your Alibaba Cloud account. You can log on to the Alibaba Cloud Management Console and view the account ID on the Security Settings page.

AliyunIOTAccessingDataHubRole indicates a service-linked role that is defined in RAM. This role is used to grant access permissions on DataHub to IoT Platform. You can go to the RAM Roles page of the RAM console to manage RAM roles.

Example


{
    "role":{
        "roleArn": "acs:ram::${uid}:role/aliyuniotaccessingdatahubrole",
        "roleName": "AliyunIOTAccessingDataHubRole"
    },
    "ProjectName": "test_project_name",
    "RegionName": "cn-shanghai",
    "TopicName": "test_topic"
}
The configurations of the MNS type

Parameter

Description

themeName

The name of the MNS topic that you want to use to receive data.

regionName

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

role

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

{"roleArn":"acs:ram::${uid}:role/aliyuniotaccessingmnsrole","roleName": "AliyunIOTAccessingMNSRole"}

${uid} specifies the ID of your Alibaba Cloud account. 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 RAM. This role is used to grant access permissions on MNS to IoT Platform. You can go to the RAM Roles page of the RAM console to manage RAM roles.

Example


{
    "themeName": "test_name",
    "role":{
        "roleArn": "acs:ram::${uid}:role/aliyuniotaccessingmnsrole",
        "roleName": "AliyunIOTAccessingMNSRole"
    },
    "regionName": "cn-shanghai"
}
The configurations of the ONS type
Note To grant permissions on Message Queue for Apache RocketMQ to IoT Platform, call the SDK or log on to the Message Queue for Apache RocketMQ console. IoT Platform must be authorized to publish messages to Message Queue for Apache RocketMQ. Then, you can create a rule action to forward data to the service.

Parameter

Description

instanceId

The ID of the Message Queue for Apache RocketMQ instance that you want to use to receive data.

topic

The name of the Message Queue for Apache RocketMQ topic that you want to use to receive data.

regionName

The code of the region where Message Queue for Apache RocketMQ is deployed. Example: cn-shanghai.

You can forward data only within the same region.

role

The information about the RAM role. You can grant IoT Platform the access to Message Queue for Apache RocketMQ by assigning a service role to IoT Platform. The syntax of a RAM role:

{"roleArn":"acs:ram::${uid}:role/aliyuniotaccessingmqrole","roleName": "AliyunIOTAccessingMQRole"}

${uid} specifies the ID of your Alibaba Cloud account. You can log on to the Alibaba Cloud Management Console and view the account ID on the Security Settings page.

AliyunIOTAccessingFCRole is a service-linked role that is defined in the RAM console. This role is used to grant access permissions on Message Queue for Apache RocketMQ to IoT Platform. You can go to the RAM Roles page of the RAM console to manage RAM roles.

Example


{
    "instanceId": "${MQ_INST_ID}",
    "role":
    {
        "roleArn": "acs:ram::${uid}:role/aliyuniotaccessingmqrole",
        "roleName": "AliyunIOTAccessingMQRole"
    },
    "regionName": "cn-shanghai",
    "topic": "test_topic"
}
The configurations of the FC type

Parameter

Description

functionName

The name of the function that you want to use to receive data.

serviceName

The name of the service that you want to use to receive data.

regionName

The ID of the region where Function Compute is deployed. Example: cn-shanghai.

role

The information about the RAM role. You can grant IoT Platform the access to Function Compute by assigning a service role to IoT Platform. The syntax of a RAM role:

{"roleArn":"acs:ram::${uid}:role/aliyuniotaccessingfcrole","roleName": "AliyunIOTAccessingFCRole"}

${uid} specifies the ID of your Alibaba Cloud account. You can log on to the Alibaba Cloud Management Console and view the account ID on the Security Settings page.

AliyunIOTAccessingFCRole is a service-linked role that is defined in RAM. This role is used to grant access permissions on Function Compute to IoT Platform. You can go to the RAM Roles page of the RAM console to manage RAM roles.

Example


{
    "role":
    {
        "roleArn": "acs:ram::${uid}:role/aliyuniotaccessingfcrole",
        "roleName": "AliyunIOTAccessingFCRole"
    },
    "functionName": "${function_name}",
    "serviceName": "${service_name}",
    "regionName": "cn-shanghai"
}

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

Response parameters

Parameter Type Example Description
Code String iot.system.SystemException

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

Destination Struct

The returned information about the data destination after the data destination is created.

Configuration String {"topic":"/a1POX0c****/device1/user/get","topicType":1}

The configuration data of the data destination.

DestinationId Long 1003

The ID of the data destination.

IsFailover Boolean false

Indicates whether the data destination is configured to forward error operation data. The error operation data indicates the data that failed to be forwarded and re-forwarded to other Alibaba Cloud services

  • true: Error operation data is forwarded.
  • false: Normal data instead of error operation data is forwarded.

Default value: false.

Name String DataPurpose

The name of the data destination.

Type String REPUBLISH

The operation that is performed on the data of the data destination.

UtcCreated String 2022-03-27T12:45:43.000Z

The time when the data destination was created. The time is displayed in UTC. Format: yyyy-MM-dd'T'HH:mm:ss.SSS'Z'.

ErrorMessage String A system exception occurred.

The error message returned if the request fails.

RequestId String E4C0FF92-2A86-41DB-92D3-73B60310D25E

The ID of the request. The ID uniquely identifies this request.

Success Boolean true

Indicates whether the call was successful.

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

Examples

Sample requests

http(s)://iot.cn-shanghai.aliyuncs.com/?Action=CreateDestination
&Configuration={"topic":"/a1POX0c****/device1/user/get","topicType":1}
&Name=DataPurpose
&Type=REPUBLISH
&<Common request parameters>

Sample success responses

XML format 

<CreateDestinationResponse>
  <Destination>
        <Type>REPUBLISH</Type>
        <UtcCreated>2022-03-27T12:45:43.000Z</UtcCreated>
        <Configuration>{"topic":"/a1POX0c****/device1/user/get","topicType":1}</Configuration>
        <IsFailover>false</IsFailover>
        <DestinationId>1003</DestinationId>
        <Name>DataPurpose</Name>
  </Destination>
  <RequestId>E4C0FF92-2A86-41DB-92D3-73B60310D25E</RequestId>
  <Success>true</Success>
</CreateDestinationResponse>

JSON format 

{
    "Destination": {
        "Type": "REPUBLISH",
        "UtcCreated": "2022-03-27T12:45:43.000Z",
        "Configuration": "{\"topic\":\"/a1POX0c****/device1/user/get\",\"topicType\":1}",
        "IsFailover": false,
        "DestinationId": 1003,
        "Name": "DataPurpose"
    },
    "RequestId": "E4C0FF92-2A86-41DB-92D3-73B60310D25E",
    "Success": true
}