Porta do Proxy

Envie seu próprio tráfego pelas saídas da FourA a partir de qualquer cliente que aceite uma URL de proxy: um navegador, uma ferramenta de download, um scraper que você já executa. A porta de proxy abre um túnel para o destino especificado e copia bytes em ambas as direções, transmitindo o que a API JSON não suporta: streams, downloads grandes e sessões inteiras de navegador.

Conectando

As credenciais são obtidas no dashboard. Crie um usuário de proxy em Proxy na barra lateral para gerar um username e senha. Eles são separados da sua chave de API de propósito: o handshake do proxy trafega em texto não criptografado a cada conexão, e um usuário de proxy pode ser rotacionado sem afetar sua integração com a API. Consulte Proxy Users.

curl -x http://USERNAME:PASSWORD@proxy.foura.ai:34004 https://example.com

import requests

proxy = "http://USERNAME:PASSWORD@proxy.foura.ai:34004"
r = requests.get("https://example.com", proxies={"https": proxy, "http": proxy})
print(r.status_code)

A porta aceita apenas CONNECT. Um destino https:// é encapsulado por qualquer cliente. Um destino http:// comum funciona quando seu cliente também o encapsula (curl: --proxytunnel); um cliente que, em vez disso, encaminha a requisição comum para o proxy recebe 405 Method Not Allowed.

Opções são passadas no Username

Tudo após a credencial é uma lista de pares -key-value, em qualquer ordem:

USERNAME-network-premium-country-de-session-a1

Os valores são palavras em minúsculas. Um traço dentro de um valor inicia uma nova opção, portanto -city-new-york é interpretado como duas opções e é recusado. Uma chave desconhecida também é recusada, nunca descartada: um -contry-de digitado incorretamente retorna como um 400 que lista as chaves suportadas, em vez de ser atendido a partir do país incorreto.

Todas as opções, exceto network, fallback e session, aceitam any, que limpa um valor salvo no usuário proxy para esta única conexão.

Três combinações são recusadas com um 400 em vez de serem atendidas parcialmente:

• state, city, asn, os ou lifetime na rede compartilhada. A rede compartilhada é selecionada por país e nada mais específico; adicione -network-premium para direcionar a uma cidade.
• -fallback-premium junto com -network-premium. Um fallback não tem função na rede para a qual ele faz o fallback.
• Segmentação mais precisa com um fallback ativo. Um fallback pode ou não ser acionado, logo uma cidade que ele só poderia atender às vezes é recusada.

Sessões

Na rede compartilhada, uma sessão nomeada mantém a mesma saída pelo tempo em que você continuar usando-a, em uma janela deslizante de dez minutos. Se essa saída parar de funcionar, a sessão migra para outra em vez de falhar. Um navegador controlado através da porta deve sempre conter um nome de sessão: o carregamento de uma página abre dezenas de conexões e, sem uma sessão, cada uma sai de um endereço diferente.

Na rede premium, uma sessão nomeada retém seu endereço por lifetime minutos, ou pelo padrão da rede quando você não define um.

Padrões salvos

A segmentação salva em um proxy user no painel se aplica a cada conexão feita com ele, permitindo que o username continue curto. Qualquer valor inserido no username prevalece para essa conexão específica, e any redefine para o valor salvo. Um padrão premium salvo consome saldo apenas quando o seu plano permite; caso contrário, a conexão é atendida pela rede compartilhada e o túnel ainda é aberto.

CONNECT headers

Um cliente que pode adicionar headers à request CONNECT pode enviar as mesmas opções como headers. Um header tem prioridade sobre a mesma opção definida no username.

curl -x http://USERNAME:PASSWORD@proxy.foura.ai:34004 \
  --proxy-header "X-Foura-Country: de" \
  https://example.com

Responses

Um túnel que se abre responde 200 Connection established. Toda recusa feita após a verificação das suas credenciais contém um header X-Foura-Error com o motivo em uma linha, portanto leia esse header antes de qualquer outra coisa.

Limits

• Túneis abertos simultaneamente e aberturas de túnel por minuto dependem do seu plano e são contabilizados por conta, e não por usuário de proxy: emitir uma segunda credencial não concede uma franquia adicional. Seus números estão em Usage & Limits.
• Encontrar uma saída leva até 45 segundos antes de a porta desistir com um erro 502. Uma sessão que já possui uma saída normalmente se conecta em bem menos de um segundo.
• Um túnel sem tráfego de bytes em nenhuma das direções é encerrado após dois minutos de inatividade.
• Quando a porta é atualizada, os túneis já abertos têm pouco menos de três minutos para finalizar e depois são encerrados, enquanto novas conexões continuam abrindo. Downloads longos ou transmissões contínuas devem se reconectar quando o túnel fechar.
• Um usuário de proxy que você desativar ou excluir no dashboard para de se autenticar dentro de um minuto.

Metering

Os bytes que passam pela porta contam para a largura de banda na sua página Usage & Limits, e os bytes por uma saída premium também contam para o seu tráfego premium: são os mesmos bytes, reportados duas vezes, nunca somados. Quando um túnel abre, o tráfego de saídas premium que a porta tentou mas não utilizou também conta como tráfego premium. Tentativas não utilizadas na rede compartilhada não são contabilizadas, e nada é contabilizado quando nenhum túnel abre.

O tráfego padrão que a porta pode usar é o do seu plano. Em um plano vendido por créditos, a porta tem seus próprios gigabytes incluídos, e a página Billing vende pacotes adicionais; em um plano vendido por tráfego, ela consome do mesmo pool da API. Quando esse limite acaba, novas conexões são recusadas até que o período seja reiniciado ou você adicione mais, e os e-mails de uso informam quando isso ocorre.

Assim que a franquia premium se esgota, as três formas de acesso a essa rede recebem respostas distintas, propositalmente. Uma conexão que especifica -network-premium é recusada com um 403 informando o motivo, pois um cliente que solicitou gastar créditos e foi atendido silenciosamente por outra rota continuaria fazendo requisições e tentando conciliar um consumo premium que nunca aparece. Um fallback não é acionado, e um padrão premium salvo no proxy user sofre downgrade para a rede compartilhada, que ainda abre o túnel: nenhuma dessas opções escolheu gastar créditos nesta conexão específica.

Related

• Proxy Users: Crie proxy users e monte uma connection string no dashboard
• Proxy Request: A alternativa via JSON API, com retentativas e validação integradas
• Reuse a Proxy Across Requests: Mantendo uma única saída na JSON API
• Usage & Limits: Largura de banda e tráfego premium em relação ao seu plano