API获取HTTP/SOCKS5代理：白名单配置方法

API获取代理前，接口信息要确认哪些内容？

API接入前先确认请求方式、接口地址、鉴权方法、返回字段和代理协议，这五项决定了代码应该如何写。

如果接口文档没有明确说明某个参数，不建议直接根据参数名称推断功能。可以先用最少参数发送请求，确认基础接口能够返回结果，再逐步增加业务条件。

白名单和账号密码有什么区别？

白名单和账号密码解决的是访问授权问题，但配置位置不同。

白名单的判断对象是请求来源公网IP，不是开发电脑的内网地址。使用云服务器时，还要确认实例的实际出口地址是否经过共享网关或弹性公网IP转换。

账号密码则需要注意特殊字符编码。如果密码中包含@、:或其他保留字符，直接拼到代理URL中可能造成解析错误，建议按照客户端文档完成编码，或者使用独立的鉴权参数。

如何用API获取一条HTTP代理？

下面用最小请求演示基本流程。接口域名、请求路径和参数仅作占位，接入时必须替换为服务商提供的实际内容。

curl "https://[API域名]/[接口路径]?count=1&format=json"

如果使用白名单鉴权，请先在控制台添加当前服务器公网IP。若使用账号密码，按照服务商要求传递鉴权参数：

curl "https://[API域名]/[接口路径]?count=1&format=json&username=[用户名]&password=[密码]"

返回结果可能是JSON，也可能是纯文本。假设接口返回JSON，解析时应至少校验以下字段：

{
  "code": 0,
  "data": [
    {
      "host": "203.0.113.10",
      "port": 8080,
      "protocol": "http"
    }
  ]
}

这里的字段仅用于展示程序处理逻辑，实际字段名称应以服务商返回内容为准。

Python示例：

import requests

api_url = "https://[API域名]/[接口路径]"

api_response = requests.get(
    api_url,
    params={
        "count": 1,
        "format": "json"
    },
    timeout=10
)

api_response.raise_for_status()
payload = api_response.json()

item = payload["data"][0]
proxy = f'{item["protocol"]}://{item["host"]}:{item["port"]}'

proxies = {
    "http": proxy,
    "https": proxy
}

business_response = requests.get(
    "https://[自有测试地址]",
    proxies=proxies,
    timeout=10
)

print(business_response.status_code)

这里有两个独立请求。第一个请求获取代理，第二个请求验证代理是否能够建立业务连接。不要把第一个请求成功直接当作第二个请求成功。

SOCKS5代理应该怎么接入？

SOCKS5代理需要客户端具备对应协议支持，配置时通常使用socks5或socks5h协议标识。

Python使用requests时，可以安装SOCKS扩展：

pip install requests[socks]

然后配置代理：

import requests

proxy = "socks5h://[用户名]:[密码]@[代理地址]:[端口]"

proxies = {
    "http": proxy,
    "https": proxy
}

response = requests.get(
    "https://[自有测试地址]",
    proxies=proxies,
    timeout=10
)

print(response.status_code)

如果使用白名单鉴权，代理URL中可以不放账号密码，但当前服务器公网IP必须已经加入白名单。若HTTP可以正常连接而SOCKS5失败，应优先检查客户端依赖、协议名称、端口和账号密码格式。

API获取代理后，怎样做连接验证？

连接验证至少应包含四项内容：

1. HTTP状态码是否符合预期。
2. 连接是否在设定时间内完成。
3. 返回内容是否完整。
4. 连续请求时是否出现大量重复或空响应。

建议将验证结果记录下来，而不是只在控制台打印一次状态码。

def check_proxy(proxy_url, test_url):
    try:
        response = requests.get(
            test_url,
            proxies={
                "http": proxy_url,
                "https": proxy_url
            },
            timeout=10
        )

        return {
            "ok": response.ok,
            "status_code": response.status_code,
            "elapsed_ms": round(response.elapsed.total_seconds() * 1000),
            "error": None
        }
    except requests.RequestException as exc:
        return {
            "ok": False,
            "status_code": None,
            "elapsed_ms": None,
            "error": str(exc)
        }

测试地址应当属于自有系统、公开测试页面或已获得授权的业务范围。验证结果只能说明当前测试条件下的连接情况，不能直接推导出所有目标业务的结果。

白名单配置时，哪些细节最容易出错？

白名单配置最常见的问题不是添加操作本身，而是添加了错误的IP。

青果网络支持白名单和账密两种验证方式，白名单数量为256个。对于网站采集器、APP大数据分析等需要分环境运行的任务，可以将开发、测试和生产环境分别记录，减少配置变更带来的排查成本。

HTTP、HTTPS和SOCKS5应该怎么选？

协议选择主要取决于客户端能力和业务链路，不建议只根据名称判断。

• HTTP代理：适合大多数HTTP客户端和公开数据请求。
• HTTPS代理：适合需要建立加密连接的请求，具体配置取决于客户端。
• SOCKS5代理：适合支持通用代理协议的客户端和网络工具。
• 带账密代理：适合需要在请求中传递账号信息的环境。
• 白名单代理：适合服务器出口相对固定的环境。

如果业务需要每次请求自动换IP，可以考虑隧道代理；如果程序需要自行获取并管理代理列表，可以考虑API提取型短效代理。两种方式的运维边界不同，前者减少客户端管理工作，后者保留更多调度控制权。

API接入落到哪类产品更合适？

我们青果网络在广告监测和舆情监测这类持续请求场景中，通常先区分“程序自己管理代理列表”还是“服务端自动完成IP切换”。需要程序按返回结果自行选择代理时，短效代理更适合做API提取；希望请求自动换IP、减少本地维护时，隧道代理更适合。短效代理存活时间为1-30分钟，隧道代理则按请求数计费并在每次请求时换IP。具体选择还要结合协议、请求节奏和网络环境判断。

常见问题

Q1：API获取代理时，白名单必须填写本机IP吗？

A：不一定。白名单应填写实际发起API请求和代理请求的公网IP。开发电脑、本地网络和云服务器的出口地址可能不同，建议在实际运行环境中确认公网出口后再配置。

Q2：HTTP代理和SOCKS5代理能用同一段代码吗？

A：请求逻辑可以复用，但代理参数和客户端支持方式可能不同。HTTP代理通常直接配置地址和端口，SOCKS5还要确认客户端已经安装对应依赖，并使用正确的协议标识。

Q3：为什么接口能返回代理，但业务请求仍然超时？

A：接口返回只说明提取动作完成，不代表代理连接已经验证。应继续检查代理协议、端口、白名单、账号密码、客户端超时时间和当前网络环境，并记录每次失败的具体阶段。

Q4：白名单最多可以配置多少个IP？

A：青果网络当前公共属性支持256个白名单IP。实际配置时建议按开发、测试、生产和备用环境进行管理，删除长期不用的地址，避免后续排查时难以确认请求来源。

Q5：全球HTTP代理适合在国内服务器上测试吗？

A：不适合。全球HTTP代理不支持在中国大陆地区网络环境下使用。测试前应先确认服务器所在网络环境和产品线路范围，否则会把网络边界问题误判为API或代码问题。