# ResetInstance

## 1. 接口描述

本接口(ResetInstance)用于重装一台虚拟机实例操作系统。

#### 准备工作

* 查询镜像：调用[DescribeImages](/api-reference/cn/compute/zec/image/describeimages.md)可以查询到需要重装的操作系统镜像信息。

{% hint style="info" %}
**注意事项**

* 如果指定了`imageId`参数，则使用指定的镜像重装；否则按照实例当前使用的镜像进行重装。
* 不支持跨操作系统类型(`osType`)重装。比如操作系统类型`linux` 重装成 `windows`
* 实例的系统盘大小必须大于或等于被重装镜像的大小。否则操作将被拒绝。
* 系统盘将会被格式化，并重置；请确保系统盘中无重要文件。
* 密码与keyPair必须且只能指定其中一种。
* 重装系统必须在实例为关机状态才能进行。
* `Windows` 和 `Generic` 不支持指定 `key_id` SSH登录。
* 重装实例后进入`DEPLOYING`(部署中)的状态。如果实例的最新状态变为`RUNNING`(开机)，则代表操作成功，如果变为`REINSTALL_FAILED`(重装失败)，则代表操作失败，请与管理员联系；实例的状态可以通过调用 [`DescribeInstancesStatus`](/api-reference/cn/compute/zec/instance/describeinstancesstatus.md) 接口查询。
  {% endhint %}

## 2. 请求参数

以下请求参数列表仅列出了接口中需要的请求参数

| 参数名称         | 必选 | 类型      | 描述                                                                                                                                                                                                             |
| ------------ | -- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| instanceId   | 是  | String  | 要重装的实例ID。                                                                                                                                                                                                      |
| password     | 否  | String  | <p>实例的新密码。</p><p>与keyId必须指定其中的一种（Windows和Generic类型的镜像无法指定密码和key）。</p><p>必须包含以下3种格式的字符：大小写字母: \[a-zA-Z]数字: 0-9特殊字符: \~!@$^\*-\_=+。</p>                                                                          |
| keyId        | 否  | String  | <p>密钥ID。</p><p>与password必须指定其中的一种（Windows和Generic类型的镜像无法指定密码和key）。</p><p>可调用接口DescribeKeyPairs来获得最新的密钥对信息。</p><p>关联密钥后，就可以通过对应的私钥来访问实例；密钥与密码不能同时指定，同时Windows操作系统不支持指定密钥。</p><p>示例值：key-YWD2QFOl。</p>           |
| imageId      | 否  | String  | <p>指定重装的的镜像ID。</p><p>可以通过<a href="https://github.com/zenlayer/zenlayercloud-api-doc-cn/blob/main/zec/instance/describeimages.md">DescribeImages</a>取返回信息中的<code>imageId</code>字段。</p><p>如果不指定，会根据当前镜像进行重装。</p> |
| timezone     | 否  | String  | 操作系统时区设置。                                                                                                                                                                                                      |
| enableAgent  | 否  | Boolean | <p>是否启用 QEMU Guest 代理 (QGA)。</p><p>默认值：false</p>                                                                                                                                                               |
| instanceName | 否  | String  | <p>修改的实例名称。</p><p>2～63个字符。</p><p>仅支持输入字母、数字、-和英文句点(.)。</p>                                                                                                                                                     |
| userData     | 否  | String  | 初始化命令。                                                                                                                                                                                                         |

## 3. 响应结果

| 参数名称      | 类型     | 描述                                                       |
| --------- | ------ | -------------------------------------------------------- |
| requestId | String | <p>唯一请求 ID。</p><p>每次请求都会返回。定位问题时需要提供该次请求的 requestId。</p> |

## 4. 代码示例

{% tabs %}
{% tab title="示例" %}
**重装系统。**

```json
POST /api/v2/zec HTTP/1.1
Host: console.zenlayer.com
Content-Type: application/json
X-ZC-Action: ResetInstance
<Common Request Params>

Request：
{
  "instanceId": "<instanceId>",
  "imageId": "ubuntu2022",
  "password": "Example+123",
  "enableAgent": true
}

Response：
{
  "requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D3",
  "response": {
    "requestId": "T05992D0C-7E8B-4047-B0C0-780F2CD549D3"
  }
}
```

{% endtab %}
{% endtabs %}

## 5. 开发者工具

Zenlayer Cloud API 2.0 提供了配套的[开发工具集（SDK）](/api-reference/cn/api-introduction/toolkit.md)，未来会陆续支持更多开发语言，方便快速接入和使用Zenlayer的产品和服务。

## 6. 错误码

下面包含业务逻辑中遇到的错误码，其他错误码见[公共错误码](/api-reference/cn/api-introduction/instruction/commonerrorcode.md)

| HTTP状态码 | 错误码                                      | 说明              |
| ------- | ---------------------------------------- | --------------- |
| 400     | INVALID\_IMAGE\_AGENT\_NOT\_SUPPORT      | 镜像不支持Agent。     |
| 400     | INVALID\_IMAGE\_KEY\_PAIR\_NOT\_SUPPORT  | 镜像不支持ssh密钥对。    |
| 404     | INVALID\_IMAGE\_NOT\_FOUND               | 镜像不存在。          |
| 400     | INVALID\_IMAGE\_PASSWORD\_NOT\_SUPPORT   | 操作系统不支持指定密码。    |
| 400     | INVALID\_IMAGE\_SIZE\_EXCEED             | 镜像大小超过指定系统盘的大小。 |
| 400     | INVALID\_IMAGE\_STATUS                   | 镜像的状态不支持此操作。    |
| 400     | INVALID\_OS\_TYPE\_NOT\_SAME             | 操作系统类型不一致，无法操作。 |
| 400     | INVALID\_PARAMETER\_USER\_DATA\_EXCEED   | 实例命令超过长度限制。     |
| 404     | INVALID\_INSTANCE\_NOT\_FOUND            | 服务器实例不存在。       |
| 404     | INVALID\_KEY\_PAIR\_NOT\_FOUND           | SSH密钥对不存在。      |
| 400     | INVALID\_KEY\_PAIR\_NOT\_SUPPORT         | 存在不支持的ssh key。  |
| 400     | INVALID\_LOGIN\_SETTING\_CONFLICT        | 密码和密钥对不能同时设置。   |
| 400     | INVALID\_PASSWORD\_MALFORMED             | 密码格式错误。         |
| 400     | UNSUPPORTED\_OPERATION\_INSTANCE\_STATUS | 实例状态不支持此操作。     |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.console.zenlayer.com/api-reference/cn/compute/zec/instance/resetinstance.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.