文档首页/ 部署 CodeArts Deploy/ API参考（联盟区域）/ API/ 主机管理/ 新建主机 （推荐）
更新时间：2025-12-25 GMT+08:00
在线调试
CLI示例
分享

新建主机 （推荐）

功能介绍

在指定主机集群下新建主机。

调用方法

请参见如何调用API。

URI

POST /v1/resources/host-groups/{group_id}/hosts

表1 路径参数

参数

是否必选

参数类型

描述

group_id

是

String

参数解释：

主机集群id。

约束限制：

不涉及。

取值范围：

只能由英文字母、数字组成，且长度为32个字符。

默认取值：

不涉及。

请求参数

表2 请求Header参数

参数

是否必选

参数类型

描述

Content-Type

是

String

参数解释：

消息体的类型（格式）。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

X-Auth-Token

是

String

参数解释：

用户Token。 通过调用IAM服务接口获取（响应消息头中X-Subject-Token的值）。

约束限制：

不涉及。

取值范围：

字符串，长度不超过20000个字符。

默认取值：

不涉及。
表3 请求Body参数

参数

是否必选

参数类型

描述

host_name

是

String

参数解释：

主机名称。

约束限制：

不涉及。

取值范围：

只能由中文字符、英文字母、数字及"-"、"_"、"."组成，且长度为[3-128]个字符。

默认取值：

不涉及。

ip

是

String

参数解释：

主机IP。

约束限制：

不涉及。

取值范围：

IPV4格式的公网IP地址或IPV6地址

默认取值：

不涉及。

port

是

Integer

参数解释：

主机ssh端口。

约束限制：

不涉及。

取值范围：

0-65535。

默认取值：

不涉及。

os

是

String

参数解释：

主机操作系统类型。

约束限制：

不涉及。

取值范围：

  • windows：windows操作系统类型。

  • linux：linux操作系统类型。

默认取值：

不涉及。

as_proxy

是

Boolean

参数解释：

是否是代理机。

约束限制：

不涉及。

取值范围：

  • true：是代理机。

  • false：非代理机。

默认取值：

不涉及。

proxy_host_id

否

String

参数解释：

代理机id。

约束限制：

不涉及。

取值范围：

只能由英文字母、数字组成，且长度为32个字符。

默认取值：

不涉及。

authorization

是

HostAuthorizationRequestBody object

参数解释：

登录主机鉴权，使用密码登录则填写密码即可，使用密钥则填写密钥，二选一即可。

约束限制：

不涉及。

install_icagent

否

Boolean

参数解释：

是否安装icagent。

约束限制：

不涉及。

取值范围：

  • true：是。

  • false：否。

默认取值：

不涉及。
表4 HostAuthorizationRequestBody

参数

是否必选

参数类型

描述

username

是

String

参数解释：

登录主机用户名。

约束限制：

不涉及。

取值范围：

只能由字母、数字、下划线、中划线、点号、 @ 符号组成，长度[2-32]字符。

默认取值：

不涉及。

password

否

String

参数解释：

密码，认证类型为0时，密码必填。

约束限制：

不涉及。

取值范围：

不能包含空格、换行符、回车符、制表符、双引号和单引号，且长度[5-32]个字符。

默认取值：

不涉及。

private_key

否

String

参数解释：

密钥，认证类型为1时，密钥必填。

约束限制：

不涉及。

取值范围：

最大长度不超过5000个字符。

默认取值：

不涉及。

trusted_type

是

Integer

参数解释：

登录主机时认证类型。

约束限制：

不涉及。

取值范围：

  • 0：密码认证。

  • 1：密钥认证。

默认取值：

0

响应参数

状态码：200

表5 响应Body参数

参数

参数类型

描述

status

String

参数解释：

请求成功、失败状态。

取值范围：

  • success：请求成功。

  • failed：请求失败。

id

String

参数解释：

主机id。

取值范围：

只能由英文字母、数字组成，且长度为32个字符。

请求示例

新建主机时需填写主机基本信息，信息包含主机名称、IP地址、端口、用户名、密码等。

https://{endpoint}/v1/resources/host-groups/ab7647b0863c4e969c8949d38d591339/hosts

{
  "host_name" : "100.101.28.215",
  "ip" : "100.101.28.215",
  "port" : "22",
  "os" : "linux",
  "as_proxy" : false,
  "proxy_host_id" : "",
  "authorization" : {
    "username" : "root",
    "password" : "*****",
    "private_key" : "",
    "trusted_type" : 0
  },
  "install_icagent" : true
}

响应示例

状态码：200

OK 请求响应成功

{
  "status" : "success",
  "id" : "300d6d2e53624d0da08b182099ad10f7"
}

状态码

状态码

描述

200

OK 请求响应成功

错误码

请参见错误码。

父主题： 主机管理