# 切换裸金属服务器的操作系统 - ChangeBaremetalServerOs #### 功能介绍 切换裸金属服务器的操作系统。切换操作系统支持密码或者密钥注入。 ![](https://support.huaweicloud.com/api-bms/public_sys-resources/note_3.0-zh-cn.png) 切换操作系统属于异步API，接口调用成功只表示请求下发成功，任务执行结果请通过[查询Job状态 - ShowJobInfos](https://support.huaweicloud.com/api-bms/bms_api_0640.html)API获取。 #### 约束 - 关机状态或者切换操作系统失败的裸金属服务器，才能执行切换操作。 - 使用私有镜像创建的裸金属服务器，请确保已经安装了Cloud-init（Linux镜像）或Cloudbase-init（Windows镜像）。如使用未安装Cloud-init或Cloudbase-init的镜像，该接口不能注入密钥或密码。公共镜像默认已安装Cloud-init或Cloudbase-init。 - 执行切换操作系统任务时，请勿并行执行其他操作，否则可能会引起切换操作系统失败。 - 目前Windows镜像不支持注入密码，Linux镜像的user_data为加密后的密码。 #### 调试 您可以在[API Explorer](https://console.huaweicloud.com/apiexplorer/#/openapi/BMS/doc?api=ChangeBaremetalServerOs)中调试该接口。 #### 授权信息 账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限。 - 如果使用角色与策略授权，具体权限要求请参见[权限和授权项](https://support.huaweicloud.com/api-bms/bms_api_0900.html)。 - 如果使用身份策略授权，需具备如下身份策略权限。 | 授权项 | 访问级别 | 资源类型（\*为必须） | 条件键 | 别名 | 依赖的授权项 | |:---|:---|:---|:---|:---|:---| | bms:servers:changeOS | write | instance\* | - g:ResourceTag/\ - g:EnterpriseProjectId - bms:KmsKeyId - evs:Encrypted - bms:ImageId - bms:SSHKeyPairName | - | - | #### URI POST /v1/{project_id}/baremetalservers/{server_id}/changeos 参数说明请参见[表1]。 表1参数说明 | 参数 | 是否必选 | 描述 | |:---|:---|:---| | X-Auth-Token | 是 | 用户Token。通过调用IAM服务获取用户Token接口获取(响应消息头中X-Subject-Token的值) | | project_id | 是 | 项目ID。 获取方式请参见[获取项目ID](https://support.huaweicloud.com/api-bms/bms_api_appendix_03.html)。 | | server_id | 是 | 裸金属服务器ID。 可以从裸金属服务器控制台查询，或者通过调用[查询裸金属服务器详情列表 - ListBareMetalServers](https://support.huaweicloud.com/api-bms/bms_api_0609.html)获取。 | #### 请求参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | os-change | 是 | Object | 标记为切换裸金属服务器OS操作。详情请参见[表2]。 | 表2os-change字段数据结构说明 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | adminpass | 否 | String | 裸金属服务器管理员账号的初始登录密码。 其中，Linux管理员账户为root，Windows管理员账户为Administrator。 建议密码复杂度如下： - 长度为8-26位。 - 密码至少必须包含大写字母、小写字母、数字和特殊字符（!@$%\^-_=+\[{}\]:,./?）中的三种。 - 密码不能包含用户名或用户名的逆序。 说明： - 对于Windows裸金属服务器，不能包含用户名中超过两个连续字符的部分。 - 对于Linux裸金属服务器也可使用user_data字段实现密码注入，此时adminpass字段无效。 - adminpass和keyname不能同时有值。 - adminpass和keyname如果同时为空，此时，metadata中的user_data属性必须有值。 | | keyname | 否 | String | 密钥名称。 密钥可以通过[创建和导入SSH密钥（OpenStack原生）](https://support.huaweicloud.com/api-bms/bms_api_0740.html)API创建，或者使用[查询SSH密钥列表（OpenStack原生）](https://support.huaweicloud.com/api-bms/bms_api_0738.html)API查询已有的密钥。 | | userid | 否 | String | 用户ID（登录管理控制台，进入我的凭证，即可看到"用户ID"）。 | | imageid | 是 | String | 镜像ID。 镜像ID可以从镜像服务控制台获取，或者参考《镜像服务API参考》的"[查询镜像列表](https://support.huaweicloud.com/api-ims/ims_03_0602.html)"章节查询。 在使用"查询镜像列表"API查询时，可以添加过滤字段"?virtual_env_type=Ironic"来筛选裸金属服务器镜像。 | | metadata | 否 | Object | 切换裸金属服务器的元数据。详情请参见[表3]。 | 表3metadata字段数据结构说明 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | user_data | 否 | String | 切换裸金属服务器过程中待注入的Linux镜像root密码，用户自定义初始化密码。 注：修改密码脚本需经base64编码。 建议密码复杂度如下： - 长度为8-26位。 - 密码至少必须包含大写字母（A-Z）、小写字母（a-z）、数字（0-9）和特殊字符（!@$%\^-_=+\[{}\]:,./?）中的三种。 示例： base64编码前： - Linux服务器： ``` #!/bin/bash echo user_test > /home/user.txt ``` - Windows服务器： ``` rem cmd echo 111 > c:\aaa.txt ``` base64编码后： - Linux服务器： ``` IyEvYmluL2Jhc2gKZWNobyB1c2VyX3Rlc3QgPiAvaG9tZS91c2VyLnR4dA== ``` - Windows服务器： ``` cmVtIGNtZAplY2hvIDExMSA+IGM6XGFhYS50eHQ= ``` | | __system__encrypted | 否 | String | metadata中表示加密功能的字段，0代表不加密，1代表加密。 该字段不存在时，系统盘默认为不加密。 该字段值为0时，__system__cmkid不生效。 | | __system__cmkid | 否 | String | 用户主密钥ID，是metadata中表示加密功能的字段，与__system__encrypted配合使用。 说明： 请参考[查询密钥列表](https://support.huaweicloud.com/api-dew/ListKeys.html)，通过HTTPS请求获取密钥ID。 | | __system__encryption_algorithm | 否 | String | 创建加密卷支持指定加密算法。 取值范围： - AES_256：通用的高级加密算法。 - SM4：国密算法。 说明： - __system__encrypted、__system__cmkid均有效才支持设置。 - 如果不设置，默认值为AES_256。 | #### 请求示例 ``` POST https://{BMS Endpoint}/v1/bbf1946d374b44a0a2a95533562ba954/baremetalservers/cf2a8b97-b5c6-47ef-9714-eb27adf26e5b/changeos ``` ``` { "os-change": { "keyname": "$key_name", "imageid": "04dc740a-5820-4ab6-9d01-8cd3a6577296", "userid": "7e25b1da389f4697a79df3a0e5bd494e", "metadata": { "user_data": "$USER_DATA" } } } ``` #### 响应参数 - 正常响应要素 表4正常响应要素说明 | 名称 | 参数类型 | 说明 | |:---|:---|:---| | jobId | String | 提交任务成功后返回的任务ID，用户可以使用该ID对任务执行情况进行查询。 如何根据job_id来查询Job的执行状态，请参考[查询Job状态 - ShowJobInfos](https://support.huaweicloud.com/api-bms/bms_api_0640.html)。 | - 异常响应要素 表5异常响应要素说明 | 名称 | 参数类型 | 说明 | |:---|:---|:---| | error | 字典数据结构 | 提交任务异常时返回的异常信息，详情请参见[表6]。 | 表6error数据结构 | 名称 | 参数类型 | 说明 | |:---|:---|:---| | message | String | 任务异常错误信息描述。 | | code | String | 任务异常错误信息编码。 | #### 响应示例 - 正常响应 ``` { "jobId": "9288ec8d769dbc9b01769dc8f261002f" } ``` #### 返回值 正常返回值： | 返回值 | 说明 | |:---|:---| | 200 | 服务器已成功处理了请求。 | 其他返回值请参考[状态码](https://support.huaweicloud.com/api-bms/bms_api_0801.html)。 #### 错误码 请参考[错误码](https://support.huaweicloud.com/api-bms/bms_api_0802.html)。