还原实例 RestorePod--云手机-火山引擎

文档中心

立即注册

导航

还原实例 RestorePod

最近更新时间：2025.07.02 18:19:05首次发布时间：2025.07.01 16:02:28

本接口用于将一个或多个已备份至云盘的实例的数据恢复至云机的本地存储中，以再次启动和使用实例。适用于本地存储业务。
支持随机分配云机还原，也支持指定云机还原。

使用说明

如需更换实例归属机房（Dc），请先调用 MigratePod 接口将待还原实例数据迁移至目标机房，再使用本接口还原实例。
如需指定云机进行实例还原，请确保目标云机具备相应的承载能力。具体参看 SpecifyHostRestore 参数说明。
本接口为异步接口，调用成功仅表示任务已提交。您可以通过以下任意途径，获取任务最终执行结果：
- 配置“任务执行回调”和“子任务执行回调”，具体操作请参考云手机回调服务接入指南；
- 根据生成的任务 ID，调用 GetTaskInfo 接口查询任务执行结果；
- 通过控制台任务管理页面查询。
实例还原完成后，云盘中的实例数据将被自动删除，以释放存储空间。

注意事项

还原过程中，请勿对云机执行重置、更新、重启、或退订等其他操作，否则有可能导致还原失败或实例数据损坏。
单次接口调用支持还原的实例数量上限为 100。
本接口的单用户 QPS 限制为 5 次/秒。超过限制，API 调用会被限流。

请求说明

请求方式：POST
请求地址：https://open.volcengineapi.com?Action=RestorePod&Version=2025-05-01

请求参数

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

Query

参数	类型	是否必选	示例值	描述
Action	String	是	`RestorePod`	接口名称。当前 API 的名称为 `RestorePod`。
Version	String	是	`2025-05-01`	接口版本。当前 API 的版本为 `2025-05-01`。

Body

参数	类型	是否必选	示例值	描述
ProductId	String	是	`1635714550******`	待还原实例所归属的业务 ID。
PodIdList	Array of String	否	`[7294157141458****, 7294157141458****]`	待还原的实例 ID 列表，多个实例 ID 请以英文逗号 "," 分隔。最多支持传入 100 个实例 ID。说明请确保传入的全部实例皆处于“备份完成”状态。本参数与 `SpecifyHostList` 参数必须至少择一填写，具体规则如下：若无需指定云机还原，请使用本参数传入实例 ID 列表；若需要指定云机还原，请使用 `SpecifyHostList` 传入实例 ID 列表；若本参数与 `SpecifyHostList` 中的 `PodIdList` 参数均传值，为保证还原任务的成功执行，请务必确保两组列表中的实例 ID 完全不重叠。
SpecifyHostList	Array of SpecifyHostRestore	否	`-`	云机列表，用于指定云手机实例还原到的目标云机。当 `PodIdList` 为空时，本参数必填。

SpecifyHostRestore

参数	类型	是否必选	示例值	描述
HostId	String	是	`host-7434750386952******`	实例还原的目标云机。注意目标云机上可运行的实例规格需与待还原实例规格保持一致，可通过 `DetailHost` 接口返回的 `ConfigurationCode` 参数判断。
PodIdList	Array of String	是	`[7294157141458****, 7294157141458****]`	待还原的实例 ID 列表，多个实例 ID 请以英文逗号 "," 分隔。注意待还原的实例数量不得超过目标云机剩余的可创建实例数量，可通过 `DetailHost` 接口返回的 `PodNumAvailable` 和 `PodNumOnHost` 参数判断余量。

返回参数

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

参数	类型	示例值	描述
TaskIdList	Array of String	`["7400702264829****","7400702264829****"]`	生成的异步还原任务 ID 列表。若 `PodIdList` 传入的实例来自多个区域（Zone）时，则会返回多个任务 ID。

请求示例

POST https://open.volcengineapi.com?Action=RestorePod&Version=2025-05-01
{
    "ProductId": "1635714550******",
    "PodIdList": [
        ""
    ],
    "SpecifyHostList": [
        {
            "HostId": "host-7434750386952******",
            "PodIdList": [
                "7343627425983******"
            ]
        }
    ]
}

返回示例

{
    "ResponseMetadata": {
        "Action": "RestorePod",
        "Region": "cn-north-1",
        "Service": "ACEP",
        "Version": "2025-05-01",
        "RequestId": "20230604110420****100232280022D31"
    },
    "Result": {
        "TaskIdList": [
            "7400702264829******"
        ]
    }
}

错误码

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