本文导读

功能介绍
调试
URI
请求参数
响应参数
请求示例
响应示例
状态码
错误码

展开导读

文档首页/ 设备接入 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

{
  "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

错误码

请参见错误码。

父主题： 实例管理

上一篇：实例管理

下一篇：查询实例列表

意见反馈

文档内容是否对您有帮助？

有帮助没帮助

提供反馈

提交成功！非常感谢您的反馈，我们会继续努力做到更好！

系统繁忙，请稍后重试

在使用文档中是否遇到以下问题

内容与产品页面不一致

内容不易理解

缺失示例代码

步骤不可操作

搜不到想要的内容

缺少最佳实践

意见反馈（选填）

0/500

请至少选择一项反馈信息并填写问题反馈

字符长度不能超过500

直接提交取消