文档首页/ 密码安全中心 DEW/ API参考/ API/ 管理SSH密钥对/ 密钥对任务管理/ 绑定SSH密钥对 - AssociateKeypair
更新时间：2026-05-20 GMT+08:00
查看PDF
分享

绑定SSH密钥对 - AssociateKeypair

功能介绍

给指定的虚拟机绑定（替换或重置，替换需提供虚拟机已配置的SSH密钥对私钥；重置不需要提供虚拟机的SSH密钥对私钥）新的SSH密钥对

调用方法

请参见如何调用API。

授权信息

账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限。

  • 如果使用角色与策略授权，具体权限要求请参见权限和授权项。
  • 如果使用身份策略授权，需具备如下身份策略权限。

    授权项

    访问级别

    资源类型（*为必须）

    条件键

    别名

    依赖的授权项

    kps:SSHKeyPair:bind

    Write

    SSHKeyPair *

    -

    kps:domainKeypairs:bind
    • ecs:cloudServers:createServers
    • ecs:cloudServers:deleteServers
    • ecs:cloudServers:showServer
    • ecs:cloudServers:attach
    • ecs:cloudServers:listServerBlockDevices
    • ecs:cloudServers:showServerBlockDevice
    • ecs:cloudServers:detachVolume
    • ecs:cloudServers:listServerInterfaces
    • ecs:cloudServers:listServersDetails
    • ecs:cloudServerFlavors:get
    • ecs:cloudServerQuotas:get
    • evs:types:get
    • evs:volumes:use
    • ims:images:get
    • vpc:subnets:list

URI

POST /v3/{project_id}/keypairs/associate

表1 路径参数

参数

是否必选

参数类型

描述

project_id

是

String

参数解释：

项目ID。可参考获取项目ID获取。

约束限制：

不涉及

取值范围：

以IAM服务接口返回值为准，字符长度32-32

默认取值：

不涉及

请求参数

表2 请求Header参数

参数

是否必选

参数类型

描述

X-Auth-Token

是

String

参数解释：

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

约束限制：

不涉及

取值范围：

IAM服务查询用户Token接口为准

默认取值：

不涉及
表3 请求Body参数

参数

是否必选

参数类型

描述

keypair_name

是

String

参数解释：

SSH密钥对名称

约束限制：

不涉及

取值范围：

不涉及

默认取值：

不涉及

server

是

EcsServerInfo object

参数解释：

需要绑定密钥对的虚拟机信息

约束限制：

不涉及

取值范围：

不涉及

默认取值：

不涉及
表4 EcsServerInfo

参数

是否必选

参数类型

描述

id

是

String

参数解释：

需要绑定(替换或重置)SSH密钥对的虚拟机id

约束限制：

不涉及

取值范围：

不涉及

默认取值：

不涉及

auth

否

Auth object

参数解释：

虚拟机鉴权认证类型信息

约束限制：

可选字段，替换时需要该参数，重置时不需要该参数

取值范围：

不涉及

默认取值：

不涉及

disable_password

否

Boolean

参数解释：

是否禁用虚拟机ssh登录

约束限制：

  • true：禁用虚拟机的ssh登录

  • false：不禁用虚拟机的ssh登录

取值范围：

true或false

默认取值：

false

port

否

Long

参数解释：

虚拟机SSH监听端口

约束限制：

不涉及

取值范围：

0-65535

默认取值：

22
表5 Auth

参数

是否必选

参数类型

描述

type

否

String

参数解释：

虚拟机鉴权认证类型

约束限制：

  • password: 虚拟机为密码鉴权

  • keypair: 虚拟机为密钥对鉴权

取值范围：

不涉及

默认取值：

不涉及

key

否

String

参数解释：

虚拟机鉴权密钥

约束限制：

  • type为枚举值password时，key表示密码

  • type为枚举值keypair时，key表示私钥

取值范围：

不涉及

默认取值：

不涉及

响应参数

状态码：202

表6 响应Body参数

参数

参数类型

描述

task_id

String

参数解释：

任务下发成功返回的任务ID

取值范围：

不涉及

server_id

String

参数解释：

绑定的虚拟机id

取值范围：

不涉及

status

String

参数解释：

任务下发的状态

取值范围：

  • SUCCESS: 任务下发成功

  • FAILED: 任务下发失败

error_code

String

参数解释：

任务下发失败返回的错误码

取值范围：

不涉及

error_msg

String

参数解释：

任务下发失败返回的错误描述

取值范围：

不涉及

请求示例

  • {
  "keypair_name" : "newkeypair1",
  "server" : {
    "id" : "d76baba7-ef09-40a2-87ff-3eafec0696e7",
    "auth" : {
      "type" : "keypair",
      "key" : "-----BEGINRSAPRIVATEKEY-----M..."
    }
  }
}
  • {
  "keypair_name" : "newkeypair2",
  "server" : {
    "id" : "d76baba7-ef09-40a2-87ff-3eafec0696e7"
  }
}

响应示例

状态码：202

OK

{
  "task_id" : "aee8d2fe-5484-4753-9177-5a38dc15546c"
}

状态码

状态码

描述

202

OK

错误码

请参见错误码。

父主题： 密钥对任务管理

相关文档