Creating a Device

Function

Creating a Device

URI

POST /v2/{project_id}/link/instances/{instance_id}/devices

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Project ID. The default value is default for compatibility with 20.0.Project ID. For details about how to get the project ID, see "Appendix" > "Obtaining a Project ID" in this document.
instance_id	Yes	String	Instance ID. The default value is default for compatibility with 20.0.

Request Parameters

**Table 2** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	User token. It can be obtained by calling the IAM API. The value of X-Subject-Token in the response header is the user token.

**Table 3** Request body parameters
Parameter	Mandatory	Type	Description
parent_device_id	No	Integer	Parent device ID. If there is no parent device, this parameter is left empty and the value is automatically rounded down.
product	Yes	ProductReferer object	Product.
password	No	String	Device password. The password must contain 8 to 32 characters, including at least one digit, one uppercase letter, one lowercase letter, and one special character (~!@#$%^&*()-_=+\|[{}];:<>/?).
user_name	No	String	Device user name, which is a string of 10 to 50 characters containing letters, hyphens (-), and digits.
device_name	Yes	String	Device name. The value is a string of 2 to 64 characters, which can contain letters, digits, and the following special characters: ()_,#.?''-@%&!,
node_id	Yes	String	Physical number of a device. The value is a string of 2 to 64 characters, which can contain only letters, digits, underscores (_), and hyphens (-). Generally, the MAC address or IMEI is used.
app_id	Yes	String	Application ID.
status	No	Integer	Device status. The options are as follows: 0 (enabled) and 1 (disabled). If this parameter is left empty, the default value 0 is used.
description	No	String	Description.
tags	No	Array of strings	Tag.
groups	No	Array of integers	ID of the device group to which a device belongs.
fingerprint	No	String	Certificate thumbprint

**Table 4** ProductReferer
Parameter	Mandatory	Type	Description
product_id	No	Integer	Product ID. The product ID is mandatory if the manufacturer ID and model are not set.
product_name	No	String	Product name.
manufacturer_id	No	String	Manufacturer ID. If the product ID is not specified, the manufacturer ID and model are mandatory.
model	No	String	Model. If the product ID is not specified, the manufacturer ID and model are mandatory.
protocol_type	No	Integer	Protocol type of the product. 0: mqtt 1: CoAP 2: modbus 4: opcua 5: extended protocol
product_type	No	Integer	Product type. The options are as follows: 0: common; 1: gateway.
extend_protocol_name	No	String	Extended protocol name.

Response Parameters

Status code: 201

**Table 5** Response body parameters
Parameter	Type	Description
permissions	Array of strings	Permission.
id	Integer	Device ID.
device_id	Integer	Device ID (compatible with 20.0).
product	ProductReferer object	Product.
device_name	String	Device name. The value is a string of 2 to 64 characters, which can contain letters, digits, and the following special characters: ()_,#.?''-@%&!,
instance_id	String	Instance ID.
client_id	String	Client ID, which is the unique device ID generated by the ROMA platform.
node_id	String	Physical number of a device. The value is a string of 2 to 64 characters, which can contain only letters, digits, underscores (_), and hyphens (-). Generally, the MAC address or IMEI is used.
app_name	String	Application name.
status	Integer	Device status. The options are as follows: 0: enabled; 1: disabled.
online_status	Integer	Connection status. The options are as follows: 0: disconnected; 1: online; 2: offline.
description	String	Description.
authentication	Authentication object	Authentication.
created_user	CreatedUser object	Name of the user who created the attribute.
last_updated_user	LastUpdatedUser object	User who performed the last update.
tags	Array of strings	Tag.
created_datetime	Long	Creation start time. The format is timestamp(ms) and the UTC time zone is used.
last_updated_datetime	Long	Last modification time (timestamp, in milliseconds). The UTC time zone is used.
connect_address	String	Device access address.
ssl_connect_address	String	Device access SSL address.
ipv6_connect_address	String	IPv6 address for device access. This parameter is valid only when IPv6 is enabled.
ipv6_ssl_connect_address	String	IPv6 SSL address for device access. This parameter is valid only when IPv6 is enabled.
node_type	Integer	Node type. The options are as follows: 0: direct connection; 1: gateway; 2: subdevice.
device_type	Integer	Device type: 0: common device (no child device or parent device) 1: gateway device (available for child devices) 2: child device (subject to a gateway device)
app_id	String	Application ID.
groups	Array of integers	ID of the device group to which a device belongs.
group_names	Array of strings	Name of the device group to which the device belongs.
fingerprint	String	Certificate thumbprint

**Table 6** ProductReferer
Parameter	Type	Description
product_id	Integer	Product ID. The product ID is mandatory if the manufacturer ID and model are not set.
product_name	String	Product name.
manufacturer_id	String	Manufacturer ID. If the product ID is not specified, the manufacturer ID and model are mandatory.
model	String	Model. If the product ID is not specified, the manufacturer ID and model are mandatory.
protocol_type	Integer	Protocol type of the product. 0: mqtt 1: CoAP 2: modbus 4: opcua 5: extended protocol
product_type	Integer	Product type. The options are as follows: 0: common; 1: gateway.
extend_protocol_name	String	Extended protocol name.

**Table 7** Authentication
Parameter	Type	Description
user_name	String	One-model-one-secret or one-device-one-secret username.
password	String	One-model-one-secret or one-device-one-secret password. The password must contain 8 to 32 characters, including at least one digit, one uppercase letter, one lowercase letter, and one special character (~!@#$%^&*()-_=+\|[{}];:<>/?).

**Table 8** CreatedUser
Parameter	Type	Description
user_id	String	User ID (reserved).
user_name	String	Username.

**Table 9** LastUpdatedUser
Parameter	Type	Description
user_id	String	User ID (reserved).
user_name	String	Username.

Status code: 400

**Table 10** Response body parameters
Parameter	Type	Description
error_code	String	System error code, which is the detailed error code of HTTP error codes 4xx and 5xx.
error_msg	String	Error description.
request_id	String	Message ID.

Status code: 404

**Table 11** Response body parameters
Parameter	Type	Description
error_code	String	System error code, which is the detailed error code of HTTP error codes 4xx and 5xx.
error_msg	String	Error description.
request_id	String	Message ID.

Status code: 500

**Table 12** Response body parameters
Parameter	Type	Description
error_code	String	System error code, which is the detailed error code of HTTP error codes 4xx and 5xx.
error_msg	String	Error description.
request_id	String	Message ID.

Example Requests

Create a device with protocol type as MQTT, product type as common, and device status as enabled.

{
  "parent_device_id" : 10001,
  "product" : {
    "product_id" : 10001,
    "product_name" : "testproduct",
    "manufacturer_id" : "test",
    "model" : "mate30pro",
    "protocol_type" : 0,
    "product_type" : 0
  },
  "password" : "**********",
  "device_name" : "device",
  "node_id" : "D32145A100FF",
  "app_id" : "ef3845be-091a-4ab5-869a-9de0025e2165",
  "status" : 0,
  "description" : "device",
  "tags" : [ "tag1", "tag2" ]
}

Example Responses

Status code: 201

Created

{
  "permissions" : [ "read", "access", "delete", "modify" ],
  "id" : 711537,
  "device_id" : 711537,
  "parent_device_id" : 711536,
  "parent_device_name" : "parent-device",
  "product" : {
    "product_id" : 116303,
    "product_name" : "p1",
    "manufacturer_id" : "p1",
    "model" : "p1",
    "product_type" : 0,
    "protocol_type" : 0
  },
  "device_name" : "device",
  "instance_id" : "8993a690-cf61-46af-880d-587d823d14e5",
  "client_id" : "D116303711537sGDtK",
  "node_id" : "string",
  "app_name" : "app",
  "status" : 0,
  "online_status" : 2,
  "description" : "device",
  "authentication" : {
    "user_name" : "F01A8D25FE6E4CF5A286B711B31888AE",
    "password" : "************************"
  },
  "created_user" : {
    "user_id" : "",
    "user_name" : "user"
  },
  "last_updated_user" : {
    "user_id" : "",
    "user_name" : "user"
  },
  "tags" : [ ],
  "created_datetime" : 1607408244841,
  "last_updated_datetime" : 1607422571094,
  "connect_address" : "xx.xx.xx.xx",
  "ssl_connect_address" : "xx.xx.xx.xx",
  "ipv6_connect_address" : "xx.xx.xx.xx",
  "ipv6_ssl_connect_address" : "xx.xx.xx.xx",
  "node_type" : 0,
  "device_type" : 0,
  "app_id" : "cb4b3ec0-8f7f-432f-b05e-fc149d05da5d"
}

Status code: 400

Bad Request

{
  "error_code" : "SCB.00000000",
  "error_msg" : "Parameter is not valid for operation [romalink.link-device.save]. Parameter is [parent_device_id]. Processor is [body].",
  "request_id" : "cb39e78a-afd3-4e04-901d-70468b1c23dc-1619602712496-cnnorth7a-P-romalink-service01"
}

Status code: 404

Not Found

{
  "error_code" : "ROMA.00110006",
  "error_msg" : "The resource does not exist. Check whether the resource ID ff38023c-0854-4779-847d-72528e1f5da1 is correct.",
  "request_id" : "624c8be1-39b6-47b7-941d-c159aced368a-1619602544650-cnnorth7a-P-romalink-service01"
}

Status code: 500

Internal Server Error

{
  "error_code" : "ROMA.00110002",
  "error_msg" : "The instance does not exist. project_id: 397cd10b30544c588b2f4a56d83856c4, instance_id: f3bb386a-23ec-47aa-9943-4c60ac658611",
  "request_id" : "c8c06d0a-be92-4fdf-9d10-bc20131ab158-1619593104919-cnnorth7a-P-romalink-service01"
}