本接口用于为一台或多台云手机实例批量设置代理服务。
您可以开启代理并配置详细的代理协议及规则，也可以使用本接口关闭已有的代理设置。

使用说明

1. 该接口需配合 2024/09/05 及之后日期发布的镜像使用。若您当前使用了旧版本镜像，请先升级至新版本。
2. 该接口为异步接口，调用成功仅代表“设置代理”的任务已成功创建并下发。您可以通过以下任一途径，获取任务最终的执行结果：
   • 配置任务类型为 SetProxy 的“任务执行回调”和“子任务执行回调”，具体操作请参考云手机回调服务接入指南；
   • 根据生成的 TaskId，调用 GetTaskInfo接口查询任务执行结果。

注意事项

本接口的单用户 QPS 限制为 50 次/秒、单实例 QPS 限制为 10 次/秒。超过限制，API 调用会被限流。

请求说明

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

请求参数

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

Query

Body

返回参数

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

SetProxyJob

请求示例 1

使用方案一时（version=v2），请求示例如下：

POST https://open.volcengineapi.com?Action=SetProxy&Version=2023-10-30
{
    "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",
        "dnsProtocol": "tcp",
        "udp": "true"
    }
}

返回示例 1

使用方案一时（version=v2），返回示例如下：

{
    "ResponseMetadata": {
        "Action": "SetProxy",
        "Region": "cn-north-1",
        "Service": "ACEP",
        "Version": "2023-10-30",
        "RequestId": "20230604110420****100232280022D31"
    },
    "Result": {
        "TaskId": "7299395610653******",
        "TaskAction": "SetProxy",
        "JobList": [
            {
                "JobId": "job-7294170061873******-7337159054625******",
                "PodId": "7337159054625******"
            },
            {
                "JobId": "job-7294170061874******-7337159054626******",
                "PodId": "7337159054626******"
            }
        ]
    }
}

请求示例 2

使用方案二时（version=v1），以使用 SOCKS 协议为例，请求示例如下：

POST https://open.volcengineapi.com?Action=SetProxy&Version=2023-10-30
{
    "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

使用方案二时（version=v1），返回示例如下：

{
    "ResponseMetadata": {
        "Action": "SetProxy",
        "Region": "cn-north-1",
        "Service": "ACEP",
        "Version": "2023-10-30",
        "RequestId": "20230604110420****100232280022D31"
    },
    "Result": {
        "TaskId": "7299395610653******",
        "TaskAction": "SetProxy",
        "JobList": [
            {
                "JobId": "job-7294170061873******-7337159054625******",
                "PodId": "7337159054625******"
            },
            {
                "JobId": "job-7294170061874******-7337159054626******",
                "PodId": "7337159054626******"
            }
        ]
    }
}

错误码

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

ProxyConfig 字段说明

ProxyConfig 字段用于配置代理协议及代理规则。该字段为 JSON Map 类型，当 ProxyStatus 为 1 (开启代理) 时必填。
配置分为 v2 和 v1 两种代理方案，使用 version 字段控制（需配合 2025/4/21 及之后日期发布的镜像使用）。我们强烈推荐您使用 v2 方案，该方案提供了更优的代理能力和规则支持。

方案一：使用 v2 版本代理（推荐）

当使用 v2 方案时，ProxyConfig 内所有可用参数及说明如下表所示。

使用方案一时，参考请求示例 1 和返回示例 1。

方案二：使用 v1 版本代理（旧版）

v1 方案协议特定参数

根据您在 v1 方案 type 字段中选择的协议类型，您还需要提供以下对应的参数。

使用方案二时，参考请求示例 2 和返回示例 2。