GPU API 接口

切换实例公网带宽归属

接口说明

批量切换 GPU 实例公网 IP（EIP）的带宽归属，可在账号独享带宽与平台共享带宽之间切换。切换过程中 EIP 和公网 IP 地址保持不变，不需要重启实例。

POSThttps://api.compshare.cnActionSwitchCompShareEIPShareBandwidth

使用限制

仅支持 UCloud 机房中的普通 GPU 实例，不支持 Pod/第三方数据中心实例。
同一次请求中的实例必须属于当前账号，并且与请求的 Region 一致。
实例必须绑定且只能绑定 1 个 EIP；没有 EIP 或绑定多个 EIP 时，该实例切换失败。
切换到 Company 前，当前账号必须已在该地域购买可用状态的独享带宽。
UHostIds 支持批量传入。接口逐个处理实例，可能出现部分成功、部分失败。
实例已经位于目标带宽时按成功处理，Message 返回“已在目标共享带宽中”。

请求参数

名称	类型	必填	描述	示例值
Action	String	是	接口名称	`SwitchCompShareEIPShareBandwidth`
Region	String	是	实例所在地域；`UHostIds` 中的所有实例必须与该地域一致	`cn-wlcb`
Zone	String	否	可用区；本接口按地域切换，不要求传入	`cn-wlcb-01`
ProjectId	String	否	项目 ID；不传时使用账号默认项目	`org-xxx`
UHostIds	Array of String	是	要切换的实例 ID 数组，直接以 JSON 数组传入	`["uhost-xxxx","uhost-yyyy"]`
TargetScope	String	是	目标带宽归属：`Company` 或 `Public`	`Company`

TargetScope 枚举

值	说明
`Company`	切换到当前账号在该地域购买的独享带宽
`Public`	切回平台共享带宽

请求参数不需要传 ShareBandwidthId。选择 Company 时，系统会自动使用当前账号在该地域已购买且可用的独享带宽。

响应参数

名称	类型	描述
Action	String	响应名称，固定为 `SwitchCompShareEIPShareBandwidthResponse`
RetCode	Integer	顶层返回码，`0` 表示请求已完成处理；不代表数组中每个实例都切换成功
Message	String	顶层错误信息；没有时不返回
request_uuid	String	请求唯一标识，排查问题时可提供给技术支持
Results	Array of Object	按 `UHostIds` 输入顺序返回的逐实例处理结果
Results[].UHostId	String	实例 ID
Results[].EIPId	String	实例绑定的 EIP ID；未找到 EIP 时可能不返回
Results[].Success	Boolean	该实例是否切换成功
Results[].Message	String	处理结果或失败原因
Results[].CurrentScope	String	处理结束后的带宽归属；可能为 `Company`、`Public` 或 `WithoutGPU`

CurrentScope 枚举

值	说明
`Company`	当前 EIP 位于账号独享带宽
`Public`	当前 EIP 位于平台共享带宽
`WithoutGPU`	无卡模式实例位于平台的无卡专用共享带宽

当请求 TargetScope=Public，但实例当前处于无卡模式时，系统会将 EIP 放入无卡专用共享带宽，此时成功结果中的 CurrentScope 为 WithoutGPU。恢复有卡运行后，平台会按实例状态处理对应带宽归属。

请求示例

切换到独享带宽


{
  "Action": "SwitchCompShareEIPShareBandwidth",
  "Region": "cn-wlcb",
  "UHostIds": [
    "uhost-xxxx",
    "uhost-yyyy"
  ],
  "TargetScope": "Company"
}

切回平台共享带宽


{
  "Action": "SwitchCompShareEIPShareBandwidth",
  "Region": "cn-wlcb",
  "UHostIds": ["uhost-xxxx"],
  "TargetScope": "Public"
}

Python（使用 UCloud SDK）


from ucloud.core import exc
from ucloud.client import Client
 
 
client = Client({
    "region": "cn-wlcb",
    "public_key": "my_public_key",
    "private_key": "my_private_key",
    "base_url": "https://api.compshare.cn",
})
 
try:
    response = client.ucompshare().invoke(
        "SwitchCompShareEIPShareBandwidth",
        {
            "Region": "cn-wlcb",
            "UHostIds": ["uhost-xxxx", "uhost-yyyy"],
            "TargetScope": "Company",
        },
    )
 
    for result in response.get("Results", []):
        if result.get("Success"):
            print(result["UHostId"], "切换成功：", result.get("CurrentScope"))
        else:
            print(result["UHostId"], "切换失败：", result.get("Message"))
except exc.UCloudException as error:
    print("请求失败：", error)

UHostIds 请直接传字符串数组，不要改写为 UHostIds.0、UHostIds.1。

响应示例

全部成功


{
  "Action": "SwitchCompShareEIPShareBandwidthResponse",
  "RetCode": 0,
  "request_uuid": "request-xxxx",
  "Results": [
    {
      "UHostId": "uhost-xxxx",
      "EIPId": "eip-xxxx",
      "Success": true,
      "Message": "切换成功",
      "CurrentScope": "Company"
    },
    {
      "UHostId": "uhost-yyyy",
      "EIPId": "eip-yyyy",
      "Success": true,
      "Message": "切换成功",
      "CurrentScope": "Company"
    }
  ]
}

部分成功

批量请求中的单个实例失败时，顶层 RetCode 仍可能为 0，失败原因记录在对应结果中：


{
  "Action": "SwitchCompShareEIPShareBandwidthResponse",
  "RetCode": 0,
  "request_uuid": "request-yyyy",
  "Results": [
    {
      "UHostId": "uhost-xxxx",
      "EIPId": "eip-xxxx",
      "Success": true,
      "Message": "切换成功",
      "CurrentScope": "Company"
    },
    {
      "UHostId": "uhost-not-found",
      "Success": false,
      "Message": "resource uhost-not-found does not exist"
    }
  ]
}

常见失败原因

现象或信息	处理建议
`company share bandwidth` 不存在	先在目标地域购买独享带宽，或将 `TargetScope` 改为 `Public`
独享带宽不可用	等待独享带宽恢复为可用状态后重试
`UHostIds` 与地域冲突	将不同 `Region` 的实例拆分为多个请求
找不到实例	确认实例 ID 属于当前账号，且实例资源未被删除
找不到 EIP	该实例没有公网 IP，无法切换公网带宽归属
实例存在多个 EIP	当前接口要求实例只绑定一个 EIP，请先调整 EIP 绑定关系
第三方数据中心实例参数错误	该接口仅支持 UCloud 机房实例

场景	接口或文档
查询实例当前带宽归属和是否可切换	DescribeCompShareInstance（设置 `IncludeShareBandwidth=true`）
通过控制台切换	独享带宽使用指南
了解购买、变更和退款规则	独享带宽计费说明