更新实例 UpdatePod--云手机-火山引擎

文档中心

立即注册

导航

更新实例 UpdatePod

最近更新时间：2025.11.03 17:18:49首次发布时间：2024.03.05 20:04:01

本接口用于修改已有云手机实例的配置，支持更新一个或批量更新多个实例。
可调整的配置项包括实例的名称、套餐规格、使用镜像、屏幕布局、带宽限制等。

使用说明

云盘存储业务支持使用本接口更新存储容量和套餐规格。
- 如需更改实例的套餐规格和屏幕布局，请先将实例关机，更新后的配置将在实例再次开机时生效。
- 套餐规格支持由低配置变更为高配置，也支持由高配置变更为低配置，变更前请确保当前业务下已购入对应套餐。
本地存储业务在实例处于已关机且备份完成的状态下，支持使用本接口更新实例规格。
- 按照云机规格的 ServerTypeCode 参数值，将云机规格分为以下两类：
  - g2 类型：云机规格的 ServerTypeCode 参数值为 g2.8c12g、g2.8c16g.basic、g2.8c16g.plus
  - g3 类型：云机规格的 ServerTypeCode 参数值为 g3.host8c24g256g
    g2 类型 内的实例规格支持互相更配、g3 类型 内的实例规格支持互相更配，g2 类型 和 g3 类型 之间不支持跨类型更配。关于云机规格的 ServerTypeCode 参数说明，请参见本地存储资源规格。
- 支持由低配变更为高配、高配变更为低配，但需要注意变更前实例已使用的存储容量需要小于目标实例规格存储容量的 80%。

注意事项

批量更新多个实例的配置时，实例 ID 列表（PodIdList）和实例所属机房（Dc）两者必须指定一个。
本接口的单用户 QPS 限制为 50 次/秒。超过限制，API 调用会被限流。

请求说明

请求方式：POST
请求地址：https://open.volcengineapi.com?Action=UpdatePod&Version=2023-10-30

请求参数

下表仅列出该接口特有的请求参数和部分公共参数。更多信息请见公共参数。

Query

参数	类型	是否必选	示例值	描述
Action	String	是	`UpdatePod`	接口名称。当前 API 的名称为 `UpdatePod`。
Version	String	是	`2023-10-30`	接口版本。当前 API 的版本为 `2023-10-30`。

Body

参数	类型	是否必选	示例值	描述
ProductId	String	是	`1591495366954xxxxxx`	业务 ID，管理云手机资源、开展云手机业务的标识。可登录云手机控制台，在已创建的业务卡片中获取。
PodId	String	否	`7294107154305xxxxxx`	实例 ID，用于指定需要更新配置的目标实例。说明如需修改单个实例配置，请使用本参数；如需修改多个实例配置，请根据实际需要使用 `PodIdList` 传入目标实例 ID 列表，或使用 `Dc` 指定一个机房。
PodIdList	Array of String	否	`[7294107154305xxxxxx,7294107154306xxxxxx]`	实例 ID 列表，用于指定需要更新配置的多个目标实例。说明如需修改多个实例配置，请根据实际需要使用本参数传入目标实例 ID 列表，或使用 `Dc` 指定一个机房。支持批量操作的实例数量上限为 200。如需修改单个实例配置，请使用 `PodId`。
Dc	String	否	`gdsz-ctcucm-01-5fxxxxxx`	机房 ID，单独指定本参数时，可批量更新属于该机房的所有实例的配置。说明如需修改同一机房中部分实例的配置，或不同机房中多个实例的配置，请使用 PodIdList 参数传入实例 ID 列表。支持批量操作的实例数量上限为 200。
ConfigurationCode	String	否	`enhanced`	运行实例的套餐规格 ID。说明修改套餐前，请确保当前业务下已购入目标套餐规格的实例资源。可通过 ListPodResource 接口查询。云盘存储业务需在实例关机状态下执行，实例重启后更新生效。本地存储业务需在实例处于已关机且备份完成的状态下执行。
PodName	String	否	`测试更新实例`	实例的新名称。批量修改实例名称时，此处传值将作为实例名称前缀。
ImageId	String	否	`img-7616xxxx`	镜像 ID，用于指定想要使用的新镜像。可选镜像 ID 可通过 ListImage 接口获取。说明默认情况下，更新镜像前需将云手机实例关机，新的镜像将在实例下次启动时生效。如需在实例开机状态下更新镜像，请将 `Force` 参数设置为 `true`，更新完成后实例将自动重启。不支持跨版本镜像更换。例如：不支持由 AOSP10 更换为 AOSP11，反之亦然。
Force	Boolean	否	`false`	是否可在实例开机状态下强制更新实例镜像，取值如下： `true`：可强制更新镜像，更新完成将触发实例重启； `false`：（默认）不可强制更新镜像，请先将实例关机。
DataSize	String	否	`8Gi`	为单个目标实例重新分配存储容量，仅适用于云盘存储业务（本地存储业务在更配实例规格时存储容量会随规格变化，无需重新分配）。取值范围为 1Gi～128Gi，且必须为整数。请结合实际业务情况，按需填写存储大小。
DisplayLayoutId	String	否	`single-display-landscape`	屏幕布局 ID，用于指定想要使用的屏幕显示配置。您可以选择系统提供的屏幕布局，也可以使用通过 CreateDisplayLayoutMini 接口创建的自定义屏幕布局。若使用系统屏幕布局，可选项包括： `single-display-landscape`：1080p 横屏，分辨率 19201080 像素，像素密度 320 dpi，帧率 60fps； `single-display-portrait`：1080p 竖屏，分辨率 10801920 像素，像素密度 320 dpi，帧率 60fps； `single-display-portrait-720p`：高清竖屏，分辨率 7201080 像素，像素密度 320 dpi，帧率 30fps。若使用自定义屏幕布局*，可选项可通过 ListDisplayLayoutMini 接口获取。
UpBandwidthLimit	Integer	否	`5`	实例上行带宽上限，单位为 Mbps。为确保顺畅的浏览和使用体验，建议限速值不低于 5Mbps。
DownBandwidthLimit	Integer	否	`8`	实例下行带宽上限，单位为 Mbps。为确保顺畅的浏览和使用体验，建议限速值不低于 5Mbps。
CustomRouteId	String	否	`cr-xxxx`	自定义路由规则 ID，已调用 AddCustomRoute 接口创建自定义路由规则后，可使用本参数为实例匹配或更新规则。可选的自定义路由规则 ID 可通过 ListCustomRoute 接口查询。说明需保证为实例匹配的自定义路由规则归属 Zone 与实例所在 Zone 一致。
DNSId	String	否	`dns-7417778232776xxxxxx`	自定义 DNS 规则 ID，已调用 CreateDNSRule 接口创建自定义 DNS 解析规则后，可使用本参数为实例关联或更新 DNS 规则。可选的 DNS 规则 ID 可通过 ListDNSRule 接口查询。说明需保证为实例匹配的 DNS 规则归属 Dc 与实例所在 Dc 一致。

返回参数

下表仅列出本接口特有的返回参数。更多信息请参见返回结构。

参数	类型	示例值	描述
Result	String	`success`	更新实例返回结果。

请求示例

POST https://open.volcengineapi.com?Action=UpdatePod&Version=2023-10-30
{
    "ProductId": "1591495366954xxxxxx",
    "PodId": "7294107154305xxxxxx",
    "PodName": "测试更新实例",
    "ImageId": "img-7616xxxx",
    "DataSize": "8Gi",
    "ConfigurationCode": "enhanced",
    "DisplayLayoutId": "single-display-landscape",
    "Force": true,
    "UpBandwidthLimit": 5,
    "DownBandwidthLimit": 8
}

返回示例

{
    "ResponseMetadata": {
        "RequestId": "202306041104***0100232280022D31",
        "Action": "UpdatePod",
        "Version": "2023-10-30",
        "Service": "ACEP",
        "Region": "cn-north-1"
    },
    "Result": "success"
}

错误码

您可访问公共错误码，获取更多错误码信息。