Um proxy é formado por cinco informações: um esquema, um nome de usuário, uma senha, um host e uma porta. Provedores, ferramentas e fóruns organizam essas peças em ordens diferentes, e um proxy que funciona em uma ferramenta falha em outra simplesmente porque foi colado no formato errado. Este guia mostra os layouts mais comuns, quais ferramentas esperam quais formatos e como evitar os erros que mais vemos com proxies residenciais.
Os cinco layouts comuns
Aqui está o mesmo proxy Shifter nos cinco formatos que o Proxy Generator do nosso painel pode gerar. O nome de usuário carrega a segmentação e a sessão, por isso é mais longo do que se poderia esperar.
| Formato | Exemplo |
|---|---|
scheme://user:pass@host:port | http://customer-USERNAME-sid-a1-ttl-60:PASSWORD@p.shifter.io:443 |
user:pass@host:port | customer-USERNAME-sid-a1-ttl-60:PASSWORD@p.shifter.io:443 |
host:port:user:pass | p.shifter.io:443:customer-USERNAME-sid-a1-ttl-60:PASSWORD |
user:pass:host:port | customer-USERNAME-sid-a1-ttl-60:PASSWORD:p.shifter.io:443 |
host:port@user:pass | p.shifter.io:443@customer-USERNAME-sid-a1-ttl-60:PASSWORD |
O primeiro é uma URL de verdade, definida por padrões web, e é a opção mais segura sempre que uma ferramenta a aceita. Os outros são convenções. Eles existem porque muitas ferramentas de uso em massa importam listas em texto simples, um proxy por linha, e cada ferramenta escolheu sua própria ordem.
Quais ferramentas esperam quais formatos
curl. Passe a forma de URL para -x. Se você omitir o esquema, o curl assume http://. Você também pode manter as credenciais separadas com -U username:password, o que evita problemas de codificação. Nosso guia de configuração do curl e do Postman tem exemplos completos.
Python requests e Scrapy. Ambos aceitam a forma de URL. No requests, as chaves do dicionário nomeiam o esquema do site, e os valores nomeiam o proxy, então os dois geralmente apontam para um proxy http://:
proxy = "http://customer-USERNAME:PASSWORD@p.shifter.io:443"
proxies = {"http": proxy, "https": proxy}Playwright. Recebe as partes como campos separados: server com esquema, host e porta, mais username e password. Separá-los você mesmo evita todo problema de codificação.
Puppeteer e Chrome. A flag --proxy-server recebe apenas host e porta. As credenciais passam por page.authenticate().
Gerenciadores de perfil de navegador e ferramentas de uso em massa. Muitos importam listas no formato host:port:user:pass, e alguns perguntam qual ordem sua lista usa. Verifique a tela de importação antes de colar algumas centenas de linhas.
O esquema descreve o proxy, não o site
Este é o erro mais comum que vemos. Um cliente que faz scraping de sites HTTPS escreve https:// na frente do proxy, e todas as requisições falham com um erro de TLS.
O esquema informa ao seu cliente como falar com o proxy. Um site HTTPS é alcançado através de um proxy http:// com o método CONNECT: o cliente pede ao proxy para abrir um túnel e depois executa o TLS com o site através dele. A conexão com o site continua criptografada de ponta a ponta. Escrever https://p.shifter.io:443 pede ao cliente que inicie o TLS com o próprio gateway, e nosso gateway não oferece isso, então o handshake falha. Use http:// tanto para sites HTTP quanto HTTPS, ou socks5:// se sua ferramenta preferir SOCKS.
Com SOCKS há uma segunda escolha. socks5:// resolve o nome do site na sua máquina, enquanto socks5h:// envia o nome ao proxy para que ele resolva. Se você se importa com onde as consultas DNS acontecem, leia nosso guia sobre como prevenir vazamentos de DNS.
Caracteres especiais quebram os formatos
Cada formato reserva alguns caracteres.
- Forma de URL:
@,:,/,#,?e%dentro de um nome de usuário ou senha devem ser codificados em percent-encoding. Uma senha comop@ss:wordse tornap%40ss%3Aword. - Formas separadas por dois-pontos: um dois-pontos dentro da senha desloca todos os campos depois dele, então a ferramenta lê o host ou a porta errados.
As partes de segmentação e sessão de um nome de usuário Shifter usam apenas letras, dígitos, traços e underscores, por exemplo city-new_york, então são seguras em todos os formatos. Se você definir uma senha com símbolos, a forma de URL com codificação, ou uma ferramenta com campos separados, é o caminho confiável.
Convertendo entre formatos
Quando uma ferramenta fornece um formato e seu código quer outro, converta a lista em vez de editar linhas manualmente. Esta função Python transforma qualquer um dos cinco layouts na forma de URL e codifica as credenciais:
from urllib.parse import quote
def to_proxy_url(line: str, scheme: str = "http") -> str:
line = line.strip()
if "://" in line:
return line
if "@" in line:
left, right = line.split("@", 1)
if left.rsplit(":", 1)[-1].isdigit():
hostport, creds = left, right # host:port@user:pass
else:
creds, hostport = left, right # user:pass@host:port
user, password = creds.split(":", 1)
host, port = hostport.rsplit(":", 1)
else:
parts = line.split(":")
if len(parts) != 4:
raise ValueError(f"unrecognised proxy line: {line}")
if parts[1].isdigit():
host, port, user, password = parts # host:port:user:pass
else:
user, password, host, port = parts # user:pass:host:port
return f"{scheme}://{quote(user, safe='')}:{quote(password, safe='')}@{host}:{port}"
print(to_proxy_url("p.shifter.io:443:customer-USERNAME:PASSWORD"))
# http://customer-USERNAME:PASSWORD@p.shifter.io:443Ela decide a ordem encontrando o número da porta, por isso não consegue distinguir os layouts quando um nome de usuário ou senha é composto só por dígitos. Nesse caso, pergunte a quem lhe deu a lista qual ordem ela usa.
Proxies ISP usam as mesmas formas
Proxies ISP seguem as mesmas regras com um host diferente. Todo proxy ISP se conecta através de isp.shifter.io:443, então uma linha na forma host:port:user:pass fica isp.shifter.io:443:USERNAME:PASSWORD. Cada proxy é diferenciado pelo seu nome de usuário, não por um IP e uma porta separados por proxy, o que surpreende quem está acostumado com listas no formato ip:port:user:pass.
Verificações rápidas quando um proxy não conecta
- 407 Proxy Authentication Required: o proxy foi alcançado, mas as credenciais não foram aceitas. Verifique se há um nome de usuário ou senha faltando ou trocados, ou um símbolo não codificado. Nosso guia de solução de problemas do erro 407 cobre o resto.
- Erros de TLS ou de handshake logo de início: você provavelmente escreveu
https://na frente do proxy. Mude parahttp://. - Conexão recusada ou timeouts em todas as requisições: o host ou a porta estão errados, muitas vezes porque uma linha separada por dois-pontos foi lida na ordem errada.
- Funciona no curl, falha na sua ferramenta: a ferramenta espera um layout diferente. Converta a linha, ou insira os campos separadamente.
No painel, o Proxy Generator permite escolher o protocolo e o formato antes de copiar, e baixa uma lista inteira em CSV no mesmo formato. Escolher o formato certo desde o início evita a maioria desses erros.
Fontes e referências
- RFC 3986, Uniform Resource Identifier: Generic Syntax: rfc-editor.org
- curl, a opção —proxy: curl.se
- Requests, proxies: requests.readthedocs.io
- Playwright, HTTP proxy: playwright.dev