# 设置云手机代理

为一台或多台云手机绑定代理。
- **前置条件**：`ids` 与 `uniqueIds` 至少提供一个。云手机必须属于你的团队，**不需要**已开机。传入的 `proxyId` 必须存在，否则调用被拒绝。
- **副作用**：当 `proxyId` 省略或为 `0` 时，会复用连接信息完全相同的已有代理；**若没有匹配项，则在你的团队中新建一条代理记录**。代理检测状态会被重置，上一个代理会被记录下来。
- **完成信号**：同步。**已开机的云手机会立即收到新代理——不需要重启**；已关机的在下次启动时生效。
- **重试**：重新绑定已有 `proxyId` 是幂等的；但如果请求里带的是原始连接信息，每次去重未命中都可能再新建一条代理记录。

已记录的业务错误码：`33300`, `33303`, `33320`, `14023`。 各错误码的含义见 [Error Codes](../Getting%20Started/error-codes.md)。任何接口还可能返回通用错误码。

Endpoint: POST /cloudphone/setProxy
Version: 2026-09-05
Security: Authorization

## Security:

  - `Authorization` (unknown)
    http bearer JWT

## Request fields (application/json):

  - `ids` (array)
    云手机环境 ID 列表
    Example: ["1558968155668507"]

  - `uniqueIds` (array)
    云手机环境展示序号列表（未提供 envIds 时作为对应关系使用）
    Example: [1001]

  - `proxy` (object)

  - `proxy.proxyId` (string)
    代理配置 ID（大于 0 表示复用已有代理配置；为空或 <=0 表示使用后续的详细参数创建/更新代理信息）
    Example: 10002

  - `proxy.proxyIp` (string, required)
    代理服务器 IP 地址
    Example: 192.168.1.100

  - `proxy.proxyPort` (integer, required)
    代理服务器端口
    Example: 8080

  - `proxy.proxyName` (string)
    代理配置名称/描述
    Example: test_proxy_01

  - `proxy.proxyProvider` (integer, required)
    代理类型 0:http, 1:https, 2:socks5
    Example: 2

  - `proxy.username` (string)
    代理认证用户名
    Example: admin

  - `proxy.password` (string)
    代理认证密码
    Example: pwd123

  - `proxy.refreshUrl` (string)
    刷新动态代理 IP 的 API 地址
    Example: http://api.proxy.com/refresh

  - `proxy.country` (string)
    代理所在国家代码（如 CN、US）
    Example: US

  - `proxy.state` (string)
    代理所在州/省
    Example: California

  - `proxy.city` (string)
    代理所在城市
    Example: Los Angeles

## Response 200:

  - `200` (unknown)
    成功。该接口的 `data` 恒为 null，结果由 `code` 表达。

## Response 200 fields (application/json):

  - `code` (integer)
    响应码：0 = 成功，>0 = 失败

  - `data` (null)

  - `msg` (string | null)
    错误信息；code > 0 时返回

  - `requestId` (string)
    请求唯一标识；联系支持时请提供