调用ReplaceSystemDisk更换ECS实例操作系统-云服务器 ECS-阿里云-云服务器 ECS(ECS)-阿里云帮助中心

通过更换ECS实例系统盘的方式更换操作系统。更换后系统盘的云盘ID将发生变化，原云盘会被释放。

接口说明

调用该接口前请您仔细阅读更换系统盘（更换操作系统）。

更换系统盘时，您需要注意：

不支持变更系统盘计费方式。
不支持更换系统盘的云盘类型。
系统盘挂载的 ECS 实例不能有未支付的订单。
实例的状态必须为已停止（Stopped）状态。

说明
仅适用于专有网络 VPC 类型实例。如果 ECS 实例为按量付费计费模式，且开启默认启用节省停机模式，为防止地域范围内的 ECS 实例库存不足，引起的更换系统盘后无法重启实例。您需要在停止该实例时设置为普通停机模式。具体操作，请参见 StopInstance 。
您可以通过参数SystemDisk.Size重新指定系统盘的容量大小（不能低于原系统盘容量）。
ECS 实例被安全锁定，即实例的OperationLocks参数值包含"LockReason": "security"，不支持更换系统盘。更多信息，请参见安全锁定时的 API 行为。

更换系统盘后，可通过 DescribeInstances 接口查询更换系统盘的实例的状态验证是否更换成功。如果返回值OperationLocks为空，则表示更换系统盘的操作已完成。

调试

您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。

调试

授权信息

下表是API对应的授权信息，可以在RAM权限策略语句的Action元素中使用，用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下：

操作：是指具体的权限点。
访问级别：是指每个操作的访问级别，取值为写入（Write）、读取（Read）或列出（List）。
资源类型：是指操作中支持授权的资源类型。具体说明如下：
- 对于必选的资源类型，用前面加 * 表示。
- 对于不支持资源级授权的操作，用全部资源表示。
条件关键字：是指云产品自身定义的条件关键字。
关联操作：是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限，操作才能成功。

操作

访问级别

资源类型

条件关键字

关联操作

ecs:ReplaceSystemDisk

update

Disk

acs:ecs:{#regionId}:{#accountId}:disk/{#diskId}

Image

acs:ecs:{#regionId}:{#accountId}:image/{#imageId}

*Instance

acs:ecs:{#regionId}:{#accountId}:instance/{#instanceId}

ecs:IsDiskEncrypted
ecs:IsSystemDiskEncrypted
ecs:PasswordInherit
ecs:PasswordCustomized
ecs:IsDiskByokEncrypted
ecs:IsSystemDiskByokEncrypted
ecs:LoginAsNonRoot
ecs:ImagePlatform

无

请求参数

名称	类型	必填	描述	示例值
InstanceId	string	是	指定实例的 ID。说明发起请求之前请确保目标实例状态为`已停止`（`Stopped`）。	i-bp67acfmxazb4ph****
ImageId	string	否	重置系统时使用的镜像 ID。该参数为必填参数。	m-bp67acfmxazb4ph****
SystemDisk.Size	integer	否	新的系统盘容量，单位为 GiB。取值范围：普通云盘：Max{20, 参数 ImageId 对应的镜像大小}~500。 ESSD 云盘： PL0：Max{1, 参数 ImageId 对应的镜像大小}~2048。 PL1：Max{20, 参数 ImageId 对应的镜像大小}~2048。 PL2：Max{461, 参数 ImageId 对应的镜像大小}~2048。 PL3：Max{1261, 参数 ImageId 对应的镜像大小}~2048。 ESSD AutoPL 云盘：Max{1, 参数 ImageId 对应的镜像大小}~2048。其他云盘：Max{20, 参数 ImageId 对应的镜像大小}~2048。默认值：Max{40, 参数 ImageId 对应的镜像大小}。说明超过`Max{20, 更换前的系统盘容量}`的云盘容量部分，将收取额外费用。	80
ClientToken	string	否	保证请求幂等性。从您的客户端生成一个参数值，确保不同请求间该参数值唯一。ClientToken 只支持 ASCII 字符，且不能超过 64 个字符。更多信息，请参见如何保证幂等性。	123e4567-e89b-12d3-a456-426655440000
UseAdditionalService	boolean	否	是否使用阿里云提供的虚拟机系统配置（Windows：NTP、KMS；Linux：NTP、YUM）。说明挂载系统盘时（即设备名为/dev/xvda）有效。	true
Password	string	否	是否重置 ECS 实例的用户名密码。长度为 8 至 30 个字符，必须同时包含大小写英文字母、数字和特殊符号中的三类字符。特殊符号可以是： ()`~!@#$%^&*-_+=\|{}[]:;'<>,.?/ 其中，Windows 实例不能以斜线号（/）为密码首字符。默认值：保持不变。说明如果传入`Password`参数，建议您使用 HTTPS 协议发送请求，避免密码泄露。	EcsV587!
PasswordInherit	boolean	否	是否使用镜像预设的密码。默认值：false。说明使用该参数时，Password 参数必须为空。同时您需要确保使用的镜像已经设置了密码。	false
KeyPairName	string	否	密钥对名称。说明该参数仅对 Linux 系统 ECS 实例生效。您可以为 ECS 实例绑定一个 SSH 密钥对，作为登录凭证。使用了 SSH 密钥对后，用户名密码的登录凭证方式将被禁用。	testKeyPairName
DiskId	string	否	说明该参数已废弃，为提高兼容性，建议您使用 `ImageId`。	d-bp67acfmxazb4ph****
Platform	string	否	说明已弃用。	CentOS
Architecture	string	否	说明已弃用。	i386
SecurityEnhancementStrategy	string	否	更换系统盘后，是否免费使用云安全中心服务。取值范围： Active：使用。该值仅支持公共镜像。 Deactive：不使用。该值支持所有镜像。默认值：Deactive。	Active
Encrypted	boolean	否	是否加密云盘。取值范围： true：是。 false：否。默认值：false。重要当使用共享加密镜像，创建基于加密快照的云盘时，必须指定该云盘的请求参数 Encrypted=true，以确保创建出的云盘使用的是被共享方自己的密钥。	false
KMSKeyId	string	否	系统盘对应的 KMS 密钥 ID。	e522b26d-abf6-4e0d-b5da-04b7******3c
EncryptAlgorithm	string	否	说明该参数暂未开放使用。	hide
Arn	array<object>	否	该参数暂未开放使用。
	object	否
RoleType	string	否	说明该参数暂未开放使用。	null
Rolearn	string	否	说明该参数暂未开放使用。	null
AssumeRoleFor	integer	否	说明该参数暂未开放使用。	0

返回参数

名称	类型	描述	示例值
	object
DiskId	string	新系统盘的云盘 ID。	d-bp67acfmxazb4ph****
RequestId	string	请求 ID。	473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E

示例

正常返回示例

JSON格式

{
  "DiskId": "d-bp67acfmxazb4ph****",
  "RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E"
}

异常返回示例

JSON格式

{
    "RequestId":"337568C5-64F3-4B76-8CDD-D3D8C57B5B8C",
    "DiskId":"d-j6cam2z21u4ks3dj6flb"
}

错误码

HTTP status code	错误码	错误信息	描述
400	LoginAsNonRoot.ImageNotSupport	The specified image does not support login as non-root.	此镜像不支持NonRoot登录。
400	InvalidSystemDiskSize.ValueNotSupported	The specified parameter SystemDisk.Size is invalid.
400	InvalidParameter.Conflict	The specified image does not support the specified instance type.	指定的镜像不能用于指定的实例规格。
400	InvalidSystemDiskSize.ImageNotSupportResize	The specified image does not support resize.	指定的镜像不支持扩容。
400	InvalidSystemDiskSize	The specified parameter SystemDisk.Size is invalid.
400	InvalidPassword.Malformed	The specified parameter "Password" is not valid.	指定的参数 Password 不合法
400	InvalidPasswordParam.Mismatch	The input password should be null when passwdInherit is true.	启用 PasswdInherit 后，用户名密码应该设置为空。
400	OperationDenied	The specified image contains the snapshot of the data disk. This operation is not supported.
400	InvalidDiskCategory.ValueNotSupported	The specified parameter "DiskCategory" is not valid.	指定的参数云盘类型DiskCategory无效。
400	InvalidKeyPairName.NotFound	The specified KeyPairName does not exist.	指定的 KeyPairName 不存在。
400	DependencyViolation.IoOptimize	The specified parameter InstanceId is not valid.	指定的实例 IO 优化配置不合法。
400	MissingParameter.Architecture	Architecture should not be null.	参数 Architecture 不能为空。
400	InvalidArchitecture.Malformed	Architecture is not valid.	您输入的参数 Architecture 无效，请查看该参数格式是否正确。
400	MissingParameter.Platform	Platform should not be null.	参数 Platform 不能为空。
400	InvalidPlatform.Malformed	Platform is not valid.	指定的平台无效。
400	InvalidDiskId.NotFound	The specified disk do not exist.	指定的磁盘不存在。
400	InvalidDatadisk.DiskStatusViolation	The operation is not permitted due to status of the Datadisk.	当前数据盘的状态不支持此操作。
400	InvalidDatadisk.DiskCategoryViolation	The operation is not permitted due to category of the Datadisk.	该数据盘的类型不支持该操作。
400	InvalidDatadisk.ChargeTypeViolation	The operation is not permitted due to charge type of the Datadisk.
400	MissingParameter	The input parameter "ImageId" that is mandatory for processing this request is not supplied.
400	InvalidInstance.NotFoundSystemDisk	The specified instance has no system disk.	指定的实例没有挂载系统盘。请确保指定的实例已挂载了系统盘。您可以调用 DescribeInstances 查询指定实例的信息。
400	InvalidParameter.DiskType	The specified disk type which has kms key can't convert to system disk.
400	DISK_IN_DEDICATED_BLOCK_STORAGE_CLUSTER	The disk in dedicated block storage cluster is not allowed to do this operation.
400	IncorrectDiskStatus.ReplicationStatusNotFound	Disk replication status not found.
400	IncorrectDiskStatus.InReplication	Disk already in replication.
400	InvalidInstanceType.NotSupported	The specified instanceType is not supported by the image architecture.	指定的镜像架构不支持此实例规格。
400	InvalidRegionId.NotSupportReplaceEncryptedSystemDisk	The specified region not support replace encrypted system disk.
400	InvalidStorageClusterId.CapacityNotEnough	The remaining capacity of the current dedicated storage cluster is less than the size of disk.	磁盘所在专属存储集群的可用容量不足
400	QuotaExceed.DiskCapacity	The used capacity of disk type has exceeded the quota in the zone, %s.	指定磁盘类型的已用容量超出可用区配额限制，您可以前往配额中心查询和申请提升磁盘容量配额。
400	AccountForbidden.ProductCreationLimited	The commodity must be officially operated by Aliyun and in pay-as-you-go billing method.	集团上云客户只能购买按量付费的 ECS，且不能购买第三方的商品比如由镜像市场提供的镜像。请检查参数，传入符合条件的参数重试。
400	InternalError	The requested services is not available now. Please try again later.	内部发生错误，请重试。
400	InvalidDiskName.Malformed	The specified parameter "SyatemDisk.DiskName or DataDisk.n.DiskName" is not valid.	参数中指定的磁盘名称DiskName无效。
400	InvalidParameter.Encrypted	Creating non-encrypted disks with encrypted snapshots is not supported.	不支持以加密快照创建非加密盘。
500	OperationDenied	Internal Error.
500	InternalError	The request processing has failed due to an internal error and you may retry later or contact support with the request ID.
403	LoginAsNonRoot.RegionNotSupport	The specified region does not support login as non-root.
403	InvalidSystemDiskStatus.IsTransfering	The current status of the resource does not support this operation. The system disk is transferring.
403	IncorrectDiskStatus	The current disk status does not support this operation.
403	IncorrectInstanceStatus	The current status of the resource does not support this operation.
403	InstanceLockedForSecurity	The instance is locked due to security.	您的资源被安全锁定，拒绝操作。
403	ImageNotSubscribed	The specified image has not be subscribed.
403	ImageRemovedInMarket	The specified marketplace image is not available. Or the specified user-defined image includes a product code because it is based on an image subscribed from the marketplace; and that marketplace image including the exact same product code has been removed.
403	InstanceExpiredOrInArrears	The specified operation is denied as your prepay instance is expired (prepay mode) or in arrears (afterpay mode).
403	ChargeTypeViolation	The operation is not permitted due to charge type of the instance.
403	DiskCreatingSnapshot	The operation is denied due to a snapshot of the specified disk is not completed yet.
403	IoOptimized.NotSupported	The specified image does not support IoOptimized instances.
403	ImageNotSupportInstanceType	The specified image don not support the InstanceType instance.
403	QuotaExceed.BuyImage	The specified image is from the image market. You have not bought it or your quota has been exceeded.
403	INST_HAS_UNPAID_ORDER	The instance has unpaid order.
403	OperationDenied.InstanceCreating	The specified instance is creating.
403	DependencyViolation.WindowsInstance	The instance runs Windows and does not support SSH key pair login.
403	InvalidParameter.NotMatch	%s	您输入的参数无效，请检查参数之间是否冲突。
403	ResourcesNotInSameZone	The specified instance and disk are not in the same zone.
403	OperationDenied.UnpaidOrder	The specified instance has unpaid order.	指定的实例ID已存在未支付订单，您可以登录ECS管理控制台支付。
403	InvalidHostname.MismatchImage	The hostname of the current instance can not be applied to the image you choose.
403	HibernationConfigured.InstanceOperationForbidden	The operation is not permitted due to limit of the hibernation configured instance.	不符合开启休眠选项的实例的相关限制，操作不被允许。
403	InvalidOperation.MultiAttachDisk	Multi attach disk does not support this operation.	开启多重挂载特性的云盘不支持该操作。
403	InvalidRegionId.NotSupportEncryptAlgorithm	The current region does not support creating encrypted disks with EncryptAlgorithm.
403	InvalidRegionId.NotExists	The region not exists.
403	InvalidEncryptAlgorithm	The specified parameter EncryptAlgorithm is not valid.
403	InvalidEncrypted.NotMatchKmsKeyId	The specified parameter Encrypted must be true when KmsKeyId is not empty.
403	InvalidEncrypted.NotMatchEncryptAlgorithm	The specified parameter Encrypted must be true when EncryptAlgorithm is not empty.
403	InvalidParameter.KmsNotEnabled	The specified operation need enable KMS.
403	InvalidParameter.DataEncryptedKeyCreateFailed	Failed to create the KMS data encryption key. Please verify that the current KMS key has authorized the ECS service to use it. If the issue persists; contact KMS Technical Support.
403	InvalidParameter.KMSKeyId.NotFound	The specified KMSKeyId does not exist.
403	InvalidParameter.KMSKeyId.KMSUnauthorized	ECS service does not have permission to access your KMS key. Please verify that the specified KMS key has authorized the ECS service.
403	InvalidKMSKeyId.NotSymmetric	The specified parameter KmsKeyId must be symmetric.
403	InvalidDiskId.NotSupportReplaceEncryptedSystemDisk	The specified diskId not support replace encrypted system disk.
403	NotSupportSnapshotEncrypted.DiskCategory	The specified disk category does not support creating encrypted system disks or encrypted data disks from snapshots. Check the DiskCategory or Encrypted parameter; or check your account for default encryption settings.
403	InvalidParameter.AllEmpty	The current operation does not allow both diskId and imageId to be empty. Make sure that either diskId or imageId is not empty.	当前操作不允许diskId和imageId同时为空，请确保diskId或者imageId有一个不为空。
403	InvalidParameter.Conflict	The current operation does not allow both diskId and imageId to be set. Make sure that either diskId or imageId is not empty.	当前操作不允许同时设置diskId和imageId，请确保diskId或者imageId有一个不为空。
403	OperationDenied	The current region does not support changing the image type.	当前地域不支持更换镜像类型。
403	OperationDenied.ImageNotValid	The specified Image is disabled or deleted. Please check the status of the image.
403	OperationDenied.DiskNoStock	The requested disk category is sold out in the specified zone. Please try a different disk category or another zone.	当前请求的磁盘类型在指定的可用区已经售罄。请换其它磁盘类型或者其它可用区进行重试。
403	InvalidParameter.KMSKeyId.CMKNotEnabled	The CMK (Customer Master Key) must be in an active state.	用户主密钥（CMK）需要处于活动状态。
403	InvalidParameter.KMSKeyId.CMKUnauthorized	The CMK(Customer Master Key) lacks authorization to add tags to the ECS service.	用户主密钥（CMK）未授权ECS服务添加标签权限。
403	InvalidEncrypted.NotMatchSnapshot	The specified parameter Encrypted must be set to true when creating disks with encrypted snapshots.	当使用加密快照创建磁盘时，指定的参数Encrypted必须设置为true。
403	InvalidEncrypted.NotMatchDiskDefaultEncryption	Enabling disk default encryption prevents the creation of non-encrypted disks.	启用云盘账号默认加密后，无法创建非加密磁盘。
403	InvalidPayMethod.SyncPaymentNotSupport	Synchronous payment is not supported. Use another payment method.	不支持同步支付，请选择其他支付方式。
403	InvalidOperation.ImageSecureBootUnsupported	The image does not support secure boot.	镜像不支持安全启动。
403	InvalidDiskCategory.NotSupported	The disk category is not supported in the current zone. Please call DescribeAvailableResource to check supported categories.
403	OperationDenied.KMSKeyUnauthorized	The operation is denied due to missing KMS key authorization. Please check the KMS key permissions and ensure the key is properly authorized for this operation.
404	InvalidInstanceId.NotFound	The specified InstanceId does not exist.	指定的实例ID无效。
404	InvalidImageId.NotFound	The specified ImageId does not exist.	指定的镜像在该用户账号下不存在，请您检查镜像 ID 是否正确。
404	InvalidSystemDiskSize.MoreThanMaxSize	The specified SystemDisk.Size parameter exceeds the maximum size.
404	InvalidSystemDiskSize.LessThanImageSize	The specified parameter SystemDisk.Size is less than the image size.
404	InvalidSystemDiskSize.LessThanMinSize	The specified parameter SystemDisk.Size is less than the min size.
404	NoSuchResource	The specified resource is not found.	指定的资源不存在。

访问错误中心查看更多错误码。

变更历史

更多信息，参考变更详情。