文档首页/ 设备接入 IoTDA/ API参考/ 应用侧API参考/ API/ 实例管理/ 创建设备接入实例
更新时间：2024-10-23 GMT+08:00
查看PDF
分享

创建设备接入实例

功能介绍

用户可以调用此接口创建一个设备接入实例。支持的实例规格请参见产品规格说明。

调试

您可以在API Explorer中调试该接口，支持自动认证鉴权。API Explorer可以自动生成SDK代码示例，并提供SDK代码示例调试功能。

URI

POST /v5/iot/{project_id}/iotda-instances

表1 路径参数

参数

是否必选

参数类型

描述

project_id

是

String

参数说明：项目ID。获取方法请参见 获取项目ID。

请求参数

表2 请求Header参数

参数

是否必选

参数类型

描述

X-Auth-Token

否

String

参数说明：用户Token。通过调用IAM服务 获取IAM用户Token接口获取，接口返回的响应消息头中“X-Subject-Token”就是需要获取的用户Token。简要的获取方法样例请参见 Token认证。
表3 请求Body参数

参数

是否必选

参数类型

描述

instance_type

是

String

参数说明：创建的实例类型。实例类型说明参见产品规格说明。

取值范围：

  • standard：标准版实例

  • enterprise：企业版实例

flavor

是

Flavor object

参数说明：设备接入实例的规格参数。

name

是

String

参数说明：实例名称

取值范围：由中文字符，英文字母、数字及“_”、“-”组成，且长度为[1-64]个字符。

charge_info

是

ChargeInfo object

参数说明：设备接入实例计费信息

description

否

String

参数说明：设备接入实例的描述信息。

取值范围：长度不超过256，只允许中文、字母、数字、以及_，,.。、&-等字符的组合

enterprise_project_id

否

String

参数说明：企业项目Id。此字段填写明确的企业项目Id或者0(表示默认企业项目Id)时支持企业项目特性。可以企业项目管理服务中获取。

取值范围：长度不超过36，由小写字母[a-f]、数字、连接符（-）的组成。

tags

否

Array of Tag objects

参数说明：设备接入实例的标签信息。

additional_params

否

AdditionalParams object

企业版附加参数信息。
表4 Flavor

参数

是否必选

参数类型

描述

type

是

String

参数说明：待创建设备接入实例的规格名称。详情请参见产品规格说明中的规格编码。

size

否

Integer

参数说明：待创建设备接入标准版实例的单元数量。详情请参见产品规格说明。当instance_type是standard时，该参数必填。
表5 ChargeInfo

参数

是否必选

参数类型

描述

charge_mode

是

String

参数说明：实例的付费方式。

取值范围：

  • prePaid：包年/包月

  • postPaid：按需计费

period_type

否

String

参数说明：订购设备接入实例的周期类型（包年、包月等）。charge_mode为prePaid时生效，且为必选值。

取值范围：

  • month：包月

  • year：包年

period_num

否

Integer

参数说明：订购设备接入实例的周期数。charge_mode为prePaid时生效，且为必选值。

取值范围：period_type=month（周期类型为月）时，取值为[1，9]；period_type=year（周期类型为年）时，取值为[1，3]"。

is_auto_renew

否

Boolean

参数说明：创建包年/包月实例时可指定，表示是否自动续订，续订的周期和原周期相同，且续订时会自动支付。

取值范围：

  • true：自动续订

  • false：默认值，不自动续订

is_auto_pay

否

Boolean

参数说明：创建包年/包月实例时可指定，表示是否自动从客户的账户中支付，此字段不影响自动续订的支付方式。

取值范围：true - 自动支付，从账户余额自动扣费; false - 默认值，只提交订单不支付。
表6 Tag

参数

是否必选

参数类型

描述

key

是

String

参数说明：标签键，标签的键可用字母(包含中文)、数字、空格和以下字符：下划线(_)点(.)冒号(:)等号(=)加号(+)中划线(-)以及@，首尾不能有空格字符。

value

否

String

参数说明：标签值，可为空字符串和null，标签的值可用字母(包含中文)、数字、空格和以下字符：下划线(_)点(.)冒号(:)等号(=)加号(+)中划线(-)以及@。
表7 AdditionalParams

参数

是否必选

参数类型

描述

vpc_id

是

String

参数说明：企业版实例的VPCID。

subnet_id

是

String

参数说明：企业版实例的子网ID。

security_group_id

是

String

参数说明：企业版实例的安全组ID。请确保所选安全组已放通22端口（Linux SSH登录），3389端口（Windows远程登录）和ICMP协议（Ping）。

smn_topic_urn

否

String

参数说明：SMN的topic urn, 当企业版实例创建成功时，平台将通过该topic发送通知。

ciphering_algorithm

否

String

参数说明：实例支持的加密算法。

取值范围：

  • COMMON_ALGORITHM: 通用加密算法（支持RSA，SHA256等国际通用的密码算法）

  • SM_ALGORITHM: 支持SM系列商密算法（支持SM2，SM3，SM4等国密算法）

port_info

是

Port object

企业版端口信息。创建企业版实例时必填。
表8 Port

参数

是否必选

参数类型

描述

app_https_port

否

Integer

参数说明：应用接入HTTPS协议端口，默认值：443。

app_amqps_port

否

Integer

参数说明：应用接入AMQP协议端口, 默认值：5671。

device_coap_port

否

Integer

参数说明：设备接入COAP协议端口, 默认值：5683。

device_coaps_port

否

Integer

参数说明：设备接入COAPS协议端口, 默认值：5684。

device_mqtt_port

否

Integer

参数说明：设备接入MQTT协议端口, 默认值：1883。

device_mqtts_port

否

Integer

参数说明：设备接入MQTTS协议端口, 默认值：8883。

device_https_port

否

Integer

参数说明：设备接入HTTPS协议端口, 默认值：443。

响应参数

状态码： 200

表9 响应Body参数

参数

参数类型

描述

instance_type

String

参数说明：实例类型。

取值范围：

  • standard：标准版实例

  • enterprise：企业版实例

instance_id

String

参数说明：实例ID。

取值范围：长度不超过36，由小写字母[a-f]、数字、连接符（-）的组成。

name

String

参数说明：实例名称

取值范围：由中文字符，英文字母、数字及“_”、“-”组成，且长度为[1-64]个字符。

flavor

Flavor object

参数说明：设备接入实例的规格参数。

status

String

参数说明：实例状态。

取值范围：

  • CREATING：实例正在创建

  • ACTIVE：实例正常

  • FROZEN：实例冻结

  • TRADING: 实例正在进行交易

  • MODIFYING：实例正在变更规格

  • FAILED：实例创建失败

charge_info

ChargeInfo object

参数说明：设备接入实例计费信息

description

String

参数说明：设备接入实例的描述信息。

取值范围：长度不超过256，只允许中文、字母、数字、以及_，,.。、&-等字符的组合。

enterprise_project_id

String

参数说明：企业项目Id。

tags

Array of Tag objects

参数说明: 设备接入实例的标签信息。如果实例有标签，则会有该字段，否则该字段为空。

order_id

String

参数说明：订单号，创建包年包月实例时返回该参数。

additional_params

AdditionalParams object

企业版附加参数信息。
表10 Flavor

参数

参数类型

描述

type

String

参数说明：待创建设备接入实例的规格名称。详情请参见产品规格说明中的规格编码。

size

Integer

参数说明：待创建设备接入标准版实例的单元数量。详情请参见产品规格说明。当instance_type是standard时，该参数必填。
表11 ChargeInfo

参数

参数类型

描述

charge_mode

String

参数说明：实例的付费方式。

取值范围：

  • prePaid：包年/包月

  • postPaid：按需计费

period_type

String

参数说明：订购设备接入实例的周期类型（包年、包月等）。charge_mode为prePaid时生效，且为必选值。

取值范围：

  • month：包月

  • year：包年

period_num

Integer

参数说明：订购设备接入实例的周期数。charge_mode为prePaid时生效，且为必选值。

取值范围：period_type=month（周期类型为月）时，取值为[1，9]；period_type=year（周期类型为年）时，取值为[1，3]"。

is_auto_renew

Boolean

参数说明：创建包年/包月实例时可指定，表示是否自动续订，续订的周期和原周期相同，且续订时会自动支付。

取值范围：

  • true：自动续订

  • false：默认值，不自动续订

is_auto_pay

Boolean

参数说明：创建包年/包月实例时可指定，表示是否自动从客户的账户中支付，此字段不影响自动续订的支付方式。

取值范围：true - 自动支付，从账户余额自动扣费; false - 默认值，只提交订单不支付。
表12 Tag

参数

参数类型

描述

key

String

参数说明：标签键，标签的键可用字母(包含中文)、数字、空格和以下字符：下划线(_)点(.)冒号(:)等号(=)加号(+)中划线(-)以及@，首尾不能有空格字符。

value

String

参数说明：标签值，可为空字符串和null，标签的值可用字母(包含中文)、数字、空格和以下字符：下划线(_)点(.)冒号(:)等号(=)加号(+)中划线(-)以及@。
表13 AdditionalParams

参数

参数类型

描述

vpc_id

String

参数说明：企业版实例的VPCID。

subnet_id

String

参数说明：企业版实例的子网ID。

security_group_id

String

参数说明：企业版实例的安全组ID。请确保所选安全组已放通22端口（Linux SSH登录），3389端口（Windows远程登录）和ICMP协议（Ping）。

smn_topic_urn

String

参数说明：SMN的topic urn, 当企业版实例创建成功时，平台将通过该topic发送通知。

ciphering_algorithm

String

参数说明：实例支持的加密算法。

取值范围：

  • COMMON_ALGORITHM: 通用加密算法（支持RSA，SHA256等国际通用的密码算法）

  • SM_ALGORITHM: 支持SM系列商密算法（支持SM2，SM3，SM4等国密算法）

port_info

Port object

企业版端口信息。创建企业版实例时必填。
表14 Port

参数

参数类型

描述

app_https_port

Integer

参数说明：应用接入HTTPS协议端口，默认值：443。

app_amqps_port

Integer

参数说明：应用接入AMQP协议端口, 默认值：5671。

device_coap_port

Integer

参数说明：设备接入COAP协议端口, 默认值：5683。

device_coaps_port

Integer

参数说明：设备接入COAPS协议端口, 默认值：5684。

device_mqtt_port

Integer

参数说明：设备接入MQTT协议端口, 默认值：1883。

device_mqtts_port

Integer

参数说明：设备接入MQTTS协议端口, 默认值：8883。

device_https_port

Integer

参数说明：设备接入HTTPS协议端口, 默认值：443。

请求示例

  • 创建实例，实例规格标准版中频单元，单元个数为2，计费方式为包年。

    POST https://{endpoint}/v5/iot/{project_id}/iotda-instances

{
  "instance_type" : "standard",
  "flavor" : {
    "type" : "iotda.standard.s1",
    "size" : 2
  },
  "name" : "iotda_instance",
  "charge_info" : {
    "charge_mode" : "prePaid",
    "period_type" : "year",
    "period_num" : 1,
    "is_auto_renew" : "true",
    "is_auto_pay" : "false"
  },
  "description" : "IoTDA instance for production.",
  "enterprise_project_id" : "d22e47e9-cfad-4254-8a29-d2a56a07681d",
  "tags" : [ {
    "key" : "testTagName",
    "value" : "testTagValue"
  } ]
}

  • 创建实例，实例规格标准版中频单元，单元个数为2，计费方式为按需计费。

    POST https://{endpoint}/v5/iot/{project_id}/iotda-instances

{
  "instance_type" : "standard",
  "flavor" : {
    "type" : "iotda.standard.s2",
    "size" : 2
  },
  "name" : "iotda_instance",
  "charge_info" : {
    "charge_mode" : "postPaid"
  },
  "description" : "IoTDA instance for production.",
  "enterprise_project_id" : "d22e47e9-cfad-4254-8a29-d2a56a07681d"
}

  • 创建实例，实例规格为企业版实例，计费方式为包年。

    POST https://{endpoint}/v5/iot/{project_id}/iotda-instances

{
  "instance_type" : "enterprise",
  "flavor" : {
    "type" : "iotda.enterprise.1000tps.10wonlinedevice"
  },
  "name" : "iotda_enterprise_instance",
  "charge_info" : {
    "charge_mode" : "prePaid",
    "period_type" : "year",
    "period_num" : 1,
    "is_auto_renew" : "true",
    "is_auto_pay" : "false"
  },
  "description" : "IoTDA instance for production.",
  "enterprise_project_id" : "d22e47e9-cfad-4254-8a29-d2a56a07681d",
  "additional_params" : {
    "vpc_id" : "40926909-d411-45dd-a8b4-1ebc36512345",
    "subnet_id" : "088c7d8a-f49e-4f5f-bd33-ce9b6b712345",
    "security_group_id" : "55980b43-f006-4dbf-ab58-9b0d9e712345",
    "smn_topic_urn" : "urn:smn:cn-north-7:08aaee8ae000d5182f26c00199812345:iotda_instance_create",
    "ciphering_algorithm" : "COMMON_ALGORITHM",
    "port_info" : {
      "app_https_port" : "443",
      "app_amqps_port" : "5671",
      "device_coap_port" : "5683",
      "device_coaps_port" : "5684",
      "device_mqtt_port" : "1883",
      "device_mqtts_port" : "8883",
      "device_https_port" : "443"
    }
  }
}

响应示例

状态码： 200

OK

{
  "instance_type" : "standard",
  "instance_id" : "8561675c-d8a3-4956-9884-9cf9cbdd3134",
  "flavor" : {
    "type" : "iotda.standard.s2",
    "size" : 2
  },
  "status" : "CREATING",
  "charge_info" : {
    "charge_mode" : "prePaid",
    "period_type" : "year",
    "period_num" : 1,
    "is_auto_renew" : true,
    "is_auto_pay" : false
  },
  "description" : "IoTDA instance for production.",
  "enterprise_project_id" : "d22e47e9-cfad-4254-8a29-d2a56a07681d",
  "tags" : [ {
    "key" : "testTagName",
    "value" : "testTagValue"
  } ],
  "order_id" : "CS22121614500ABCD",
  "additional_params" : null
}

状态码

状态码

描述

200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

错误码

请参见错误码。

父主题： 实例管理