更換一臺ECS實例的操作系統。更換后系統盤的云盤ID將發生變化，原云盤會被釋放。
接口說明
調用該接口前請您仔細閱讀更換操作系統（系統盤）。
更換系統盤時，您需要注意：
-
不支持變更系統盤計費方式。
-
不支持更換系統盤的云盤類型。
-
系統盤掛載的 ECS 實例不能有未支付的訂單。
-
實例的狀態必須為已停止（
Stopped）狀態。說明 僅適用于專有網絡 VPC 類型實例。如果 ECS 實例為按量付費計費模式，且開啟默認啟用節省停機模式，為防止地域范圍內的 ECS 實例庫存不足，引起的更換系統盤后無法重啟實例。您需要在停止該實例時設置為普通停機模式。具體操作，請參見 StopInstance 。 -
ECS 實例不能被安全鎖定，即實例的
OperationLocks參數值包含"LockReason": "security"。更多信息，請參見安全鎖定時的 API 行為。 -
您可以通過參數
SystemDisk.Size重新指定系統盤的容量大小。
更換系統盤后，建議您通過以下任一方式驗證是否更換成功：
-
通過 DescribeDisks 接口查詢新系統盤的狀態。如果已掛載實例，則表示更換系統盤的操作已完成。
-
通過 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} |
| 無 |
請求參數
| 名稱 | 類型 | 必填 | 描述 | 示例值 |
|---|---|---|---|---|
| InstanceId | string | 是 | 指定實例的 ID。 說明
發起請求之前請確保目標實例狀態為 已停止（Stopped）。
| i-bp67acfmxazb4ph**** |
| ImageId | string | 否 | 重置系統時使用的鏡像 ID。 未設置 | m-bp67acfmxazb4ph**** |
| SystemDisk.Size | integer | 否 | 新的系統盤容量，單位為 GiB。取值范圍：
默認值：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 | 否 | 更換系統盤后，是否免費使用云安全中心服務。取值范圍：
默認值：Deactive。 | Active |
| Encrypted | boolean | 否 | 是否加密云盤。取值范圍：
默認值：false。 | 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 | long | 否 | 說明
該參數暫未開放使用。
| 0 |
返回參數
示例
正常返回示例
JSON格式
{
"DiskId": "d-bp67acfmxazb4ph****",
"RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E"
}錯誤碼
| 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. | 指定的 SystemDisk.Size 不合法。 |
| 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. | 指定的 SystemDisk.Size 不合法。 |
| 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,does not support this operation. | 包含了數據盤快照的鏡像，不支持此操作。 |
| 400 | InvalidDiskCategory.ValueNotSupported | The specified parameter "DiskCategory" is not valid. | - |
| 400 | InvalidParameter.Conflict | %s | 您輸入的參數無效，請檢查參數之間是否沖突。%s為變量，將根據調用API的實際情況動態返回錯誤信息。 |
| 400 | InvalidSystemDiskSize.ValueNotSupported | %s | 當前操作不支持設置的系統盤大小。 |
| 400 | OperationDenied | %s | 拒絕操作。 |
| 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 | InvalidParameter.AllEmpty | %s | 您沒有輸入任何參數，請輸入必要的參數。 |
| 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 | InvalidSystemDiskSize.ValueNotSupported | The specified SystemDiskSize is not valid. | 指定的 SystemDisk.Size 不合法。 |
| 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. | 指定磁盤類型的已用容量超出可用區配額限制，您可以前往配額中心查詢和申請提升磁盤容量配額。 |
| 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, system disk is transfering. | 當前資源的狀態不支持此操作，請再系統盤停止傳輸數據后重試。 |
| 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 market image is not available, Or the specified user defined image includes product code because it is based on an image subscribed from marketplace, and that image in marketplace includeing exact the 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 is not support IoOptimized Instance. | 指定的鏡像不支持 I/O 優化型實例。 |
| 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 creating is windows, cannot use ssh key pair to login. | - |
| 403 | InvalidParameter.NotMatch | %s | 您輸入的參數無效，請檢查參數之間是否沖突。 |
| 403 | ResourcesNotInSameZone | The specified instance and disk are not in the same zone. | 指定的實例和磁盤不在同一可用區。 |
| 403 | ImageNotSupportInstanceType | The specified instanceType is not supported by instance with marketplace image. | 指定的市場鏡像不支持該實例規格。 |
| 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 | OperationDenied.ImageNotValid | %s | 當前鏡像不支持此操作。 |
| 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. | 當前操作需要開啟KMS。 |
| 403 | InvalidParameter.DataEncryptedKeyCreateFailed | Create kms data encrypted key fail. If you need further assistance, you can contact the KMS Technical Support. | 使用KMS主密鑰創建數據密鑰失敗，請聯系KMS值班同學進一步排查。 |
| 403 | InvalidParameter.KMSKeyId.NotFound | The specified KMSKeyId does not exist. | 指定的參數 KMSKeyId 不存在。 |
| 403 | InvalidParameter.KMSKeyId.CMKUnauthorized | This operation for kmsKeyId is forbidden by KMS. If you need further assistance, you can contact the KMS Technical Support. | - |
| 403 | InvalidParameter.KMSKeyId.CMKNotEnabled | The CMK needs to be enabled. | 加密云盤設置了 KMSKeyId 后，CMK必須處于啟用狀態。您可以調用密鑰管理服務的 DescribeKey 接口查詢指定CMK的相關信息。 |
| 403 | InvalidParameter.KMSKeyId.KMSUnauthorized | ECS service have no right to access your KMS. | ECS 服務無權訪問您的 KMS。 |
| 403 | InvalidKMSKeyId.NotSymmetric | The specified parameter KmsKeyId must be symmetric. | - |
| 403 | InvalidEncrypted.NotMatchKmsKeyId | The specified parameter Encrypted must be true when kmsKeyId is not null. | - |
| 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 creating encrypted data disks from snapshots. Check the DiskCategory or Encrypted parameter, or check your account for default encryption settings. | 該磁盤類型不支持創建加密系統盤或以快照方式創建加密數據盤，請檢查您輸入的磁盤類型、加密參數，或者檢查您是否做過賬號云盤默認加密配置。 |
| 403 | InvalidEncrypted.DefaultEncryptionUnsupported | The specified parameter Encrypted must be true when default encryption is enabled. | 開啟云盤默認加密后新購云盤必須為加密云盤. |
| 404 | InvalidInstanceId.NotFound | The specified InstanceId does not exist. | 指定的InstanceId不存在。 |
| 404 | InvalidInstanceId.NotFound | The specified instance 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. | 指定的參數 SystemDisk.Size 小于鏡像文件大小數值。 |
| 404 | InvalidSystemDiskSize.LessThanMinSize | The specified parameter SystemDisk.Size is less than the min size. | 指定的系統盤小于最低容量。 |
| 404 | NoSuchResource | The specified resource is not found. | 指定的資源不存在。 |
| 500 | OperationDenied | Internal Error. | 內部錯誤。 |
| 500 | InternalError | The request processing has failed due to some unknown error. | 內部錯誤，請重試。 |
| 500 | InternalError | The request processing has failed due to some unknown error, exception or failure. | 內部錯誤，請重試。 |
| 500 | OperationDenied | The specified InstanceType or Zone is not available or not authorized. | 指定的實例規格或可用區不可用或者未授權。 |
訪問錯誤中心查看更多錯誤碼。
變更歷史
| 變更時間 | 變更內容概要 | 操作 |
|---|---|---|
| 2024-12-04 | OpenAPI 描述信息更新、OpenAPI 去除了 deprecated 標記、OpenAPI 錯誤碼發生變更 | 查看變更詳情 |
| 2024-06-27 | OpenAPI 錯誤碼發生變更 | 查看變更詳情 |
| 2024-05-08 | OpenAPI 錯誤碼發生變更 | 查看變更詳情 |
| 2024-01-15 | OpenAPI 錯誤碼發生變更 | 查看變更詳情 |
| 2021-12-06 | OpenAPI 錯誤碼發生變更 | 查看變更詳情 |