本接口用于为一台或多台云手机实例批量设置代理服务。您可以开启代理并配置详细的代理协议及规则，也可以使用本接口关闭已有的代理设置。 ## 使用说明 1. 该接口需配合 2024/09/05 及之后日期发布的镜像使用。若您当前使用了旧版本镜像，请先升级至新版本。 2. 该接口为**异步接口**，调用成功仅代表“设置代理”的任务已成功创建并下发。您可以通过以下任一途径，获取任务最终的执行结果： * 配置任务类型为 `SetProxy` 的“任务执行回调”和“子任务执行回调”，具体操作请参考 [云手机回调服务接入指南](https://www.volcengine.com/docs/6394/138583)； * 根据生成的 TaskId，调用 [查询任务详情 GetTaskInfo](https://www.volcengine.com/docs/6394/2189053) 接口查询任务执行结果。 ## 请求说明 * 请求方式：POST * 请求地址：https://open.volcengineapi.com?Action=SetProxy&Version=2025\-05\-01 ## 请求参数下表仅列出该接口特有的请求参数和部分公共参数。更多信息请见 [公共参数](https://www.volcengine.com/docs/6369/67268)。 ### Query |参数 |类型 |是否必选 |示例值 |描述 | |---|---|---|---|---| |Action |String |是 |`SetProxy` |接口名称。当前 API 的名称为 `SetProxy`。 | |Version |String |是 |`2025-05-01` |接口版本。当前 API 的版本为 `2025-05-01`。 | ### Body |参数 |类型 |是否必选 |示例值 |描述 | |---|---|---|---|---| |ProductId |String |是 |`1749281594201******` |业务 ID，可在「云手机控制台\-业务管理\-业务详情」中获取 | |PodIdList |Array of String |是 |`["7337159054625******","7337159054626******"]` |需要设置代理的实例 ID 列表，可通过调用 ListPod 接口获取。列表长度上限为 100。 | |ProxyStatus |Integer |是 |`1` |是否开启代理：

* 1：开启；

* 0：关闭。 | |ProxyConfig |JSON Map |否 |`{"key":"value"}` |代理配置键值对，`ProxyStatus` 为 `1` 时必填。具体参看 [ProxyConfig 字段说明](https://www.volcengine.com/docs/6394/2189020#c34a1a19)。 | ## 返回参数下表仅列出本接口特有的返回参数。更多信息请参见 [返回结构](https://www.volcengine.com/docs/6394/75713#%E8%BF%94%E5%9B%9E%E7%BB%93%E6%9E%9C)。 |参数 |类型 |示例值 |描述 | |---|---|---|---| |TaskId |String |`7299395610653******` |任务 ID。 | |TaskAction |String |`SetProxy` |任务类型。 | |JobList |Array of [SetProxyJob](https://www.volcengine.com/docs/6394/2189020#c17e77fe) |`-` |子任务列表。参看 [SetProxyJob](https://www.volcengine.com/docs/6394/2189020#c17e77fe) 数据类型。 | ### SetProxyJob |参数 |类型 |示例值 |描述 | |---|---|---|---| |JobId |String |`job-7294170061873******-7337159054625******` |子任务 ID。 | |PodId |String |`7337159054625******` |实例 ID。 | ## 请求示例 1 使用 [方案一：使用 v2 版本代理（推荐）](https://www.volcengine.com/docs/6394/2189020#237b8df3)时（version=v2），请求示例如下： ```json POST https://open.volcengineapi.com?Action=SetProxy&Version=2025-05-01 { "ProductId": "1749281594201******", "PodIdList": [ "7337159054625******", "7337159054626******" ], "ProxyStatus": 1, "ProxyConfig": { "version": "v2", "type": "socks5", "ignoreVerify": "1", "address": "203.0.113.52", "port": "12345", "id": "your-proxy-username", "password": "your-secure-password", "oversea": "1", "proxyRules": "proxyPkgBlack", "proxyPkgBlack": "com.example.app1,com.example.app2" } } ``` ## 返回示例 1 使用 [方案一：使用 v2 版本代理（推荐）](https://www.volcengine.com/docs/6394/2189020#237b8df3)时（version=v2），返回示例如下： ```json { "ResponseMetadata": { "Action": "SetProxy", "Region": "cn-north-1", "Service": "ACEP", "Version": "2025-05-01", "RequestId": "20230604110420****100232280022D31" }, "Result": { "TaskId": "7299395610653******", "TaskAction": "SetProxy", "JobList": [ { "JobId": "job-7294170061873******-7337159054625******", "PodId": "7337159054625******" }, { "JobId": "job-7294170061874******-7337159054626******", "PodId": "7337159054626******" } ] } } ``` ## 请求示例 2 使用 [方案二：使用 v1 版本代理（旧版）](https://www.volcengine.com/docs/6394/2189020#29f03b8b)时（version=v1），以使用 SOCKS 协议为例，请求示例如下： ```json POST https://open.volcengineapi.com?Action=SetProxy&Version=2025-05-01 { "ProductId": "1749281594201******", "PodIdList": [ "7337159054625******", "7337159054626******" ], "ProxyStatus": 1, "ProxyConfig": { "version": "v1", "type": "5", "remark": "my-proxy", "oversea": "1", "address": "203.0.113.12", "port": "12345", "id": "123e4567-e89b-12d3-a456-426614174000", "password": "your-secure-password", "proxyVisible": "false", "proxyRules": "proxyPkgBlack", "proxyPkgBlack": "com.example.app1,com.example.app2" } } ``` ## 返回示例 2 使用 [方案二：使用 v1 版本代理（旧版）](https://www.volcengine.com/docs/6394/2189020#29f03b8b)时（version=v1），返回示例如下： ```json { "ResponseMetadata": { "Action": "SetProxy", "Region": "cn-north-1", "Service": "ACEP", "Version": "2025-05-01", "RequestId": "20230604110420****100232280022D31" }, "Result": { "TaskId": "7299395610653******", "TaskAction": "SetProxy", "JobList": [ { "JobId": "job-7294170061873******-7337159054625******", "PodId": "7337159054625******" }, { "JobId": "job-7294170061874******-7337159054626******", "PodId": "7337159054626******" } ] } } ``` ## 错误码您可访问 [公共错误码](https://www.volcengine.com/docs/6394/1134303)，获取更多错误码信息。 ## ProxyConfig 字段说明 `ProxyConfig` 字段用于配置代理协议及代理规则。该字段为 JSON Map 类型，当 `ProxyStatus` 为 `1` (开启代理) 时必填。配置分为 **v2** 和 **v1** 两种代理方案，使用 `version` 字段控制（需配合 2025/4/21 及之后日期发布的镜像使用）。**我们强烈推荐您使用 v2 方案**，该方案提供了更优的代理能力和规则支持。 ### 方案一：使用 v2 版本代理（推荐）当使用 v2 方案时，`ProxyConfig` 内所有可用参数及说明如下表所示。 |key |key 含义 |是否必填 |value |value 说明 | |---|---|---|---|---| |version |代理方案版本。 |是 |`v2` |String 类型。必须设置为 `v2`。 | |type |代理协议类型。 |是 |`socks5` |String 类型。指定代理协议类型，支持的取值如下：

* `socks4`：SOCKS4 协议。

* `socks5`：SOCKS5 协议。

* `http`：HTTP 协议。

* `https`：HTTPS 协议。 | |ignoreVerify |代理配置的校验模式。该参数需配合 2025/6/12 及之后日期发布的镜像使用。 |否 |`0` 或 `1` |String 类型。定义系统如何处理您提供的代理配置。

* `0`（或不设置）：**严格校验模式**（默认）。系统会根据传入的配置**测试代理服务器的网络联通性**。如果代理不通，则本次接口调用直接失败。该模式可确保配置的有效性，但会增加接口响应耗时。

* `1`：**快速信任模式**。系统**跳过所有连通性校验**，仅检查参数格式无误后直接下发配置。接口响应速度更快，但若代理服务器不通，错误将在应用实际使用时暴露（表现为无网络）。 | |address |代理服务器地址。 |是 |例如：`203.0.113.52` |String 类型。 | |port |代理服务器端口号。 |是 |例如：`12345` |String 类型。 | |id |用户 ID。 |否 |例如：`your-proxy-username` |String 类型。 | |password |密码。 |否 |例如：`your-secure-password` |String 类型。 | |oversea |是否是海外代理。 |否 |`1`：海外

其他值或不设置：国内（默认） |String 类型。 | |proxyRules |代理规则配置。 |否 |`proxyPkgBlack`、`proxyPkgWhite`、`proxyIPDomainBlack`、或 `proxyIPDomainWhite` |String 类型。若不设置则默认所有流量都走代理。

`proxyPkgBlack`：黑名单应用。

`proxyPkgWhite`：白名单应用。

`proxyIPDomainBlack`：黑名单 IP/域名。

`proxyIPDomainWhite`：白名单 IP/域名。 | |proxyPkgBlack |黑名单应用包名。 |当 `proxyRules` 为 `proxyPkgBlack` 时必填 |例如：`com.example.app1` |String 类型。多个包名以英文逗号“,”分隔。 | |proxyPkgWhite |白名单应用包名。 |当 `proxyRules` 为 `proxyPkgWhite` 时必填 |例如：`com.example.app2` |String 类型。多个包名以英文逗号“,”分隔。 | |proxyIPDomainBlack |黑名单 IP/域名。 |当 `proxyRules` 为 `proxyIPDomainBlack` 时必填 |例如：`myip.ip1.net` |String 类型。多个 IP/域名以英文逗号“,”分隔。 | |proxyIPDomainWhite |白名单 IP/域名。 |当 `proxyRules` 为 `proxyIPDomainWhite` 时必填 |例如：`myip.ip2.net` |String 类型。多个 IP/域名以英文逗号“,”分隔。 | |vpnDnsProtocol |DNS 转发协议。在开启实例代理时，用于指定系统处理 DNS 解析流量的方式，合理配置可避免代理不通时影响云手机的正常域名解析。 |否 |例如：`local` |String 类型。

* `tcp`：（默认值）将本机 DNS 查询流量劫持并转发至代理服务器。请确保您的代理服务器已支持并配置此协议，否则会造成 DNS 解析失败，导致无法联网等情况。

* `udp`：将本机发出的标准 DNS 查询包（UDP 协议，目的端口 53），通过目标地址转换（DNAT）透明地转发到指定的 DNS 服务器上。

* `local`：直连模式。放行常规 DNS 端口上的解析请求，不对 DNS 流量进行任何代理处理，直接使用云手机系统（Pod）本身的本地 DNS。 | 使用方案一时，参考 [请求示例 1](https://www.volcengine.com/docs/6394/1340579#%E8%AF%B7%E6%B1%82%E7%A4%BA%E4%BE%8B-1) 和 [返回示例 1](https://www.volcengine.com/docs/6394/1340579#%E8%BF%94%E5%9B%9E%E7%A4%BA%E4%BE%8B-1)。 ### 方案二：使用 v1 版本代理（旧版）

注意

本方案仅适用于使用 AOSP10 和 AOSP11 版本镜像的实例，AOSP13 版本镜像实例请使用方案一。

|key |key 含义 |是否必填 |value |value 说明 | |---|---|---|---|---| |version |代理方案版本。 |条件必填 |`v1` |String 类型。

若始终使用 `v1`，则可选。

若从 `v2` 切换至 `v1`，则必填。 | |type |代理协议类型。 |是 |`1` / `3` / `4` / `5` / `6` |String 类型。详见下方 [v1 方案协议特定参数](https://www.volcengine.com/docs/6394/2189020#35dc560a)。 | |remark |别名或备注信息。 |是 |例如：`my-proxy` |String 类型。 | |oversea |是否是海外代理。 |否 |`1`：海外

其他值或不设置：国内（默认） |String 类型。 | |proxyVisible |代理结果是否在云手机页面上显示。

若先设置该字段，后开启代理，则开启后立刻生效；

若先开启代理，后设置该字段，则重启实例或重新设置代理后生效。 |否 |`false` 或 `true` |String 类型。

`false`：隐藏；

`true` 或不设置：显示（默认）。 | |proxyRules |代理规则配置。 |否 |`proxyPkgBlack`、`proxyPkgWhite`、或 `proxyIPDomainBlack` |String 类型。若不设置则默认所有流量都走代理。

`proxyPkgBlack`：黑名单应用。

`proxyPkgWhite`：白名单应用。

`proxyIPDomainBlack`：黑名单 IP/域名。 | |proxyPkgBlack |黑名单应用包名。 |当 `proxyRules` 为 `proxyPkgBlack` 时必填 |例如：`com.example.app1` |String 类型。多个包名以英文逗号“,”分隔。 | |proxyPkgWhite |白名单应用包名。 |当 `proxyRules` 为 `proxyPkgWhite` 时必填 |例如：`com.example.app2` |String 类型。多个包名以英文逗号“,”分隔。 | |proxyIPDomainBlack |黑名单 IP/域名。 |当 `proxyRules` 为 `proxyIPDomainBlack` 时必填 |例如：`myip.ip.net` |String 类型。多个 IP/域名以英文逗号“,”分隔。 | #### v1 方案协议特定参数根据您在 v1 方案 `type` 字段中选择的协议类型，您还需要提供以下对应的参数。 |type 值 |协议 |所需额外参数 |参数释义及示例 | |---|---|---|---| |1 |VMESS |address，port，id |* `address`：代理服务器地址（如 `203.0.113.12`）

* `port`：代理服务器端口号（如 `12345`）

* `id`：用户 ID（如 `123e4567-e89b-12d3-a456-426614174000`）

* `password`：密码（如 `your-secure-password`）

* `encryption`：加密方式（如 `aes-256-gcm`）

* `sni`：服务器名称指示信息（如 `vless.example.com`） | |3 |VLESS |address，port，id，sni || |4 |SHADOWSOCKS |address，port，password，encryption || |5 |SOCKS |address，port，id，password || |6 |TROJAN |address，port，password，sni || 使用方案二时，参考 [请求示例 2](https://www.volcengine.com/docs/6394/2189020#8d537b74) 和 [返回示例 2](https://www.volcengine.com/docs/6394/2189020#a91ec566)。