All Products
Search
Document Center

IoT Platform:CreateProduct

更新時間:Sep 15, 2023

Creates a product.

Usage notes

If a Thing Specification Language (TSL) model is required to create a product, you must set the AliyunCommodityCode parameter to iothub_senior and specify the DataFormat parameter. For more information, see the Request parameters section of this topic.

QPS limits

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

Note

The Resource Access Management (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 of the operation for different SDKs.

Request parameters

Parameter

Type

Required

Example

Description

Action

String

Yes

CreateProduct

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

NodeType

Integer

Yes

0

The node type of the product. Valid values:

  • 0: device. Sub-devices cannot be attached to a device. A device can be directly connected to IoT Platform or connected to IoT Platform as a sub-device of a gateway. If you use the device as a sub-device of a gateway, you must specify ProtocolType.

  • 1: gateway. Sub-devices can be attached to a gateway. A gateway can manage sub-devices, maintain topological relationships with sub-devices, and synchronize topological relationships to IoT Platform.

ProductName

String

Yes

Light

The name of the product.

The name must be 4 to 30 characters in length, and can contain letters, digits, and underscores (_). Each Chinese character is counted as two characters.

Important

Each product name must be unique within the current instance.

IotInstanceId

String

No

iot-***-v64***

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 this parameter. Otherwise, the request fails.

  • If the Overview page or instance ID is not displayed in the IoT Platform console, you do not need to specify this parameter.

For more information, see Overview.

DataFormat

Integer

No

1

The data format. Valid values:

  • 0: custom data format.

  • 1: Alink JSON format.

Description

String

No

Product test

The description of the product. The description can be up to 100 characters in length.

AliyunCommodityCode

String

No

iothub_senior

The edition of the product.

  • By default, if you do not specify this parameter, a product of the Basic Edition is automatically created. You cannot use a TSL model to define the product.

  • If you want to specify this parameter, set the value to iothub_senior. In this case, a product that supports TSL models is created. You must also specify the DataFormat parameter.

Important

For products of the Basic Edition, you cannot use the online debugging feature in the IoT Platform console.

Id2

Boolean

No

false

You do not need to specify this parameter.

ProtocolType

String

No

modbus

The protocol that the devices of the product use to connect to the gateway.

If AliyunCommodityCode is set to iothub_senior and a gateway is required to connect the devices of the product to IoT Platform, you must specify this parameter.

Valid values:

  • modbus: Modbus.

  • opc-ua: Open Platform Communication Unified Architecture (OPC UA).

  • customize: custom protocol.

  • ble: Bluetooth Low Energy (BLE).

  • zigbee: ZigBee.

NetType

String

No

WIFI

The network connection method.

This parameter is required if the devices of the products are gateways or directly connected devices.

Valid values:

  • WIFI

  • CELLULAR

  • ETHERNET

  • OTHER

Default value: WIFI.

JoinPermissionId

String

No

8***

You do not need to specify this parameter.

ResourceGroupId

String

No

rg-acfmxazb4ph***

The ID of the resource group.

Important
  • IoT Platform allows you to manage only instance resources by resources groups. ResourceGroupId does not take effect in this request. You do not need to specify this parameter.

  • The resource groups that you configured in the historical requests by using this API operation are still valid.

AuthType

String

No

secret

The authentication method that is used to connect the devices of the product to IoT Platform.

You do not need to specify this parameter. The default value secret is automatically used. For more information, see Establish MQTT connections over TCP.

CategoryKey

String

No

Lighting

The identifier of the product category. If you specify this parameter, a TSL model of the product category is used. Otherwise, no TSL model is used.

You can call the ListThingTemplates operation to query the details of product categories that are predefined by IoT Platform and obtain category keys.

PublishAuto

Boolean

No

false

Specifies whether to publish the TSL model after the product is created. Valid values:

  • true

  • false

Default value: true.

ValidateType

Integer

No

1

The level of the data verification. By default, if you do not specify this parameter, weak verification is performed. Valid values:

  • 1: weak verification. IoT Platform verifies only the identifier and dataType fields of the data. All data is forwarded.

    In the IoT Platform console, the data is displayed on the TSL Data tab of the Device Details page. Data that fails to be verified is not displayed.

    You can view the data that fails to be verified in the checkFailedData parameter of the forwarded data. For more information, see Data formats.

  • 2: no verification. IoT Platform does not verify the data. All data is forwarded.

    In the IoT Platform console, the data is not displayed on the TSL Data tab of the Device Details page.

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

200

The error code returned if the request failed. For more information, see Error codes.

Data

Struct

The product information returned if the request is successful.

AliyunCommodityCode

String

iothub_senior

Indicates whether a TSL model is used for the product. Valid values:

  • iothub_senior: A TSL model is used.

  • iothub: No TSL model is used.

AuthType

String

secret

The authentication method that is used to connect the devices of the product to IoT Platform.

DataFormat

Integer

1

The data format. Valid values:

  • 0: custom data format.

  • 1: Alink JSON format.

Note

This parameter is returned only when AliyunCommodityCode is set to iothub_senior.

Description

String

Product test

The description of the product.

Id2

Boolean

false

Indicates whether ID²-based authentication is enabled. Valid values:

  • true

  • false

NodeType

Integer

0

The node type of the product. Valid values:

  • 0: device. Sub-devices cannot be attached to a device. A device can be directly connected to IoT Platform or connected to IoT Platform as a sub-device of a gateway.

  • 1: gateway. Sub-devices can be attached to a gateway. A gateway can manage sub-devices, maintain topological relationships with sub-devices, and synchronize topological relationships to IoT Platform.

Note

This parameter is returned only when AliyunCommodityCode is set to iothub_senior.

ProductKey

String

a1FlqIQ****

The ProductKey of the product. A ProductKey is a GUID issued by IoT Platform to a product.

Note

Keep the ProductKey confidential. The ProductKey is required when you perform specific operations.

ProductName

String

Test

The name of the product.

ProductSecret

String

U5tW7i44uilc****

The ProductSecret of the product.

ProtocolType

String

modbus

The protocol that the devices of the product use to connect to the gateway.

Note

This parameter is returned only when AliyunCommodityCode is set to iothub_senior.

ErrorMessage

String

A system exception occurred.

The error message returned if the request failed.

ProductKey

String

a1FlqIQ****

The ProductKey of the product. A ProductKey is a GUID that is issued by IoT Platform to a product.

RequestId

String

E55E50B7-40EE-4B6B-8BBE-D3ED55CCF565

The ID of the request.

Success

Boolean

true

Indicates whether the request was successful. Valid values:

  • true

  • false

Examples

Sample requests

https://iot.cn-shanghai.aliyuncs.com/?Action=CreateProduct
&AliyunCommodityCode=iothub_senior
&AuthType=secret
&DataFormat=1
&Description=Product test
&NodeType=0
&ResourceGroupId=rg-acfmxazb4ph****
&ProductName=Test
&ProtocolType=modbus
&CategoryKey=Lighting
&PublishAuto=false
&<Common request parameters>

Sample success responses

XML format

<CreateProductResponse>
      <Data>
            <Description>Product test</Description>
            <DataFormat>1</DataFormat>
            <ProtocolType>modbus</ProtocolType>
            <ProductKey>a1FlqIQ****</ProductKey>
            <ProductSecret>U5tW7i44uilc****</ProductSecret>
            <NodeType>0</NodeType>
            <ProductName>Test</ProductName>
            <AliyunCommodityCode>iothub_senior</AliyunCommodityCode>
            <AuthType>secret</AuthType>
            <ResourceGroupId>rg-acfmxazb4ph****</ResourceGroupId>
      </Data>
      <ProductKey>a1FlqIQ****</ProductKey>
      <RequestId>E55E50B7-40EE-4B6B-8BBE-D3ED55CCF565</RequestId>
      <Success>true</Success>
</CreateProductResponse>

JSON format

{
  "Data": {
    "Description": "Product test",
    "DataFormat": 1,
    "ProtocolType": "modbus",
    "ProductKey": "a1FlqIQ****",
    "ProductSecret": "U5tW7i44uilc****",
    "NodeType": 0,
    "ProductName": "Test",
    "AliyunCommodityCode": "iothub_senior",
    "AuthType": "secret",
    "ResourceGroupId": "rg-acfmxazb4ph****"
  },
  "ProductKey": "a1FlqIQ****",
  "RequestId": "E55E50B7-40EE-4B6B-8BBE-D3ED55CCF565",
  "Success": true
}

Error codes

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