Usare Proxy in PowerShell: Guida Pratica a Invoke-WebRequest e Invoke-RestMethod con ProxyHat

Se automatizzi raccolta dati pubblica, monitoraggio prezzi o SERP tracking da un ambiente Windows, prima o poi ti imbatti in endpoint che bloccano i range IP dei datacenter. Usare proxy in PowerShell è la soluzione più diretta: i cmdlet Invoke-WebRequest e Invoke-RestMethod supportano nativamente proxy, credenziali e sessioni persistenti, e con un gateway residenziale come ProxyHat puoi instradare ogni richiesta attraverso IP reali di ISP.

In questa guida mostriamo come configurare un PowerShell proxy con -Proxy, -ProxyCredential e -ProxyUseDefaultCredentials, come codificare geo-targeting e sessioni sticky nel nome utente, come persistere cookie e header, e come gestire retry/backoff per scraping affidabile. Tutti gli esempi usano gate.proxyhat.com sulle porte 8080 (HTTP) e 1080 (SOCKS5).

Perché serve un proxy residenziale in PowerShell

I cmdlet Invoke-WebRequest e Invoke-RestMethod si appoggiano a HttpClient nel .NET sottostante. Di default escono con l'IP della macchina locale. Se questa si trova in Azure, AWS o GCP, l'IP appartiene a range ben noti e pubblici: molti siti anti-bot (Cloudflare, Akamai, PerimeterX) li classificano come datacenter e rispondono con 403 o challenge JavaScript. Gli IP residenziali, invece, sono assegnati a ISP domestici e mobile, quindi hanno una reputazione molto più alta e superano più facilmente controlli basati su ASN.

Il problema è particolarmente evidente nel PowerShell web scraping di API pubbliche o pagine HTML: anche rispettando robots.txt e limiti di frequenza, un IP datacenter può essere bloccato dopo poche decine di richieste. Con ProxyHat puoi scegliere IP residenziali per paese e città, mantenendo sessioni sticky per minuti o ore.

1. Parametri nativi: -Proxy, -ProxyCredential e -ProxyUseDefaultCredentials

Il modo più semplice per usare un Invoke-WebRequest proxy è passare i tre parametri nativi. -Proxy accetta un URL completo (http://... o http://...), -ProxyCredential accetta un oggetto [pscredential], e -ProxyUseDefaultCredentials usa le credenziali Windows dell'utente corrente (utile in ambienti aziendali con proxy autenticati NTLM/Kerberos, non applicabile a ProxyHat).

# Esempio base: Invoke-WebRequest con proxy ProxyHat
$proxyUrl = 'http://gate.proxyhat.com:8080'

# Costruisci un PSCredential con username e password ProxyHat
$user = 'user-country-US'
$pass = 'LA_TUA_PASSWORD' | ConvertTo-SecureString -AsPlainText -Force
$cred  = New-Object System.Management.Automation.PSCredential($user, $pass)

try {
    $resp = Invoke-WebRequest -Uri 'https://httpbin.org/ip' `
        -Proxy $proxyUrl -ProxyCredential $cred `
        -UseBasicParsing -TimeoutSec 30
    $resp.Content
} catch {
    Write-Error "Richiesta fallita: $($_.Exception.Message)"
}

Lo stesso pattern vale per Invoke-RestMethod proxy:

# Invoke-RestMethod con proxy e parsing JSON automatico
$user = 'user-country-DE-city-berlin'
$pass = 'LA_TUA_PASSWORD' | ConvertTo-SecureString -AsPlainText -Force
$cred = New-Object System.Management.Automation.PSCredential($user, $pass)

$data = Invoke-RestMethod -Uri 'https://httpbin.org/json' `
    -Proxy 'http://gate.proxyhat.com:8080' -ProxyCredential $cred `
    -TimeoutSec 30

$data | ConvertTo-Json -Depth 5

ProxyHat SDK side-by-side

Il ProxyHat SDK (e l'API REST di dashboard) usa gli stessi endpoint gate.proxyhat.com:8080 e gate.proxyhat.com:1080. Non c'è una libreria PowerShell separata: si integra via parametri nativi o via [System.Net.WebProxy] come mostrato sotto. Vedi la documentazione ufficiale per i dettagli sui flag disponibili nel nome utente.

2. Geo-targeting e sessioni sticky nel nome utente

ProxyHat codifica geo-targeting e sessioni direttamente nel nome utente del proxy. Il formato è user-country-XX-city-YYYY-session-ZZZZ, dove i flag sono opzionali e componibili. Per costruire un [pscredential] dinamico in PowerShell basta concatenare le stringhe:

# Funzione helper per costruire credenziali ProxyHat dinamiche
function New-ProxyHatCredential {
    param(
        [string]$BaseUser = 'user',
        [string]$Country,
        [string]$City,
        [string]$Session,
        [string]$Password = 'LA_TUA_PASSWORD'
    )
    $u = $BaseUser
    if ($Country) { $u += "-country-$Country" }
    if ($City)   { $u += "-city-$City" }
    if ($Session){ $u += "-session-$Session" }

    $secure = $Password | ConvertTo-SecureString -AsPlainText -Force
    return New-Object System.Management.Automation.PSCredential($u, $secure)
}

# Sessione sticky negli Stati Uniti
$credUS = New-ProxyHatCredential -Country 'US' -Session 'job-001'

# IP residenziale a Berlino, Germania
$credDE = New-ProxyHatCredential -Country 'DE' -City 'berlin' -Session 'job-002'

Invoke-WebRequest -Uri 'https://httpbin.org/ip' `
    -Proxy 'http://gate.proxyhat.com:8080' -ProxyCredential $credUS `
    -UseBasicParsing

Controllo fine con [System.Net.WebProxy]

Per scenari avanzati (ad esempio quando usi HttpClient direttamente o vuoi impostare il proxy a livello di AppDomain), puoi creare un oggetto [System.Net.WebProxy] e assegnarlo a [System.Net.Http.HttpClientHandler]:

# Controllo fine con WebProxy e HttpClientHandler
Add-Type -AssemblyName System.Net.Http

$proxy = New-Object System.Net.WebProxy('http://gate.proxyhat.com:8080', $true)
$proxy.Credentials = New-ProxyHatCredential -Country 'US' -Session 'abc123'

$handler = New-Object System.Net.Http.HttpClientHandler
$handler.Proxy = $proxy
$handler.UseProxy = $true

$client = New-Object System.Net.Http.HttpClient($handler)
$client.Timeout = [TimeSpan]::FromSeconds(30)

$resp = $client.GetAsync('https://httpbin.org/ip').Result
$body = $resp.Content.ReadAsStringAsync().Result
Write-Output $body

$client.Dispose()

3. Persistere cookie e header con WebRequestSession

Quando fai scraping multi-pagina o accedi a endpoint che richiedono login, devi mantenere cookie e header tra le richieste. PowerShell usa WebRequestSession tramite i parametri -SessionVariable (crea) e -WebSession (riutilizza).

# Persistenza di cookie e header tra richieste
$proxyUrl = 'http://gate.proxyhat.com:8080'
$cred = New-ProxyHatCredential -Country 'US' -Session 'sess-001'

# Prima richiesta: crea la sessione
$resp1 = Invoke-WebRequest -Uri 'https://httpbin.org/cookies/set?token=abc123' `
    -Proxy $proxyUrl -ProxyCredential $cred `
    -SessionVariable 'session' `
    -Headers @{ 'X-Custom-Header' = 'PowerShell' } `
    -UserAgent 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) PowerShell/7' `
    -UseBasicParsing -TimeoutSec 30

# Richieste successive: riutilizza la sessione (cookie + header di base)
$resp2 = Invoke-WebRequest -Uri 'https://httpbin.org/cookies' `
    -Proxy $proxyUrl -ProxyCredential $cred `
    -WebSession $session `
    -UseBasicParsing -TimeoutSec 30

Write-Output $resp2.Content

Impostare un -UserAgent realistico è importante: molti siti rifiutano user agent predefiniti di PowerShell (come Mozilla/5.0 (Windows NT; ...) WindowsPowerShell/5.1) perché identificati come bot. Usa una stringa browser moderna.

4. Paging di un'API JSON con rotazione sessioni e retry/backoff

Ecco un esempio completo di PowerShell web scraping che pagina un'API JSON, ruota la sessione ogni 10 richieste e gestisce errori con retry/backoff esponenziale. Usiamo -MaximumRetryCount e -RetryIntervalSec nativi di PowerShell 7.

# Paging API JSON con rotazione sessioni e retry/backoff
$proxyUrl = 'http://gate.proxyhat.com:8080'
$baseUrl  = 'https://httpbin.org/anything'
$page     = 1
$pageSize = 20
$maxPages = 50
$results = @()

for ($page = 1; $page -le $maxPages; $page++) {
    # Ruota la sessione ogni 10 pagine per evitare blocchi
    $sessionId = "batch-$([math]::Floor($page / 10))"
    $cred = New-ProxyHatCredential -Country 'US' -Session $sessionId

    $uri = "$baseUrl?page=$page&size=$pageSize"

    try {
        $data = Invoke-RestMethod -Uri $uri `
            -Proxy $proxyUrl -ProxyCredential $cred `
            -MaximumRetryCount 3 -RetryIntervalSec 5 `
            -TimeoutSec 30 -Headers @{ 'Accept' = 'application/json' }

        $results += $data
        Write-Host "Pagina $page OK (session: $sessionId)"
        Start-Sleep -Milliseconds 800  # rate limiting cortese
    } catch {
        Write-Warning "Pagina $page fallita dopo retry: $($_.Exception.Message)"
        # Backoff esponenziale manuale per errori 429/503
        $backoff = [math]::Pow(2, ($page % 5))
        Start-Sleep -Seconds $backoff
        continue
    }
}

Write-Host "Totale risultati: $($results.Count)"

Il parametro -MaximumRetryCount riprova automaticamente su errori HTTP 429, 503 e timeout. Combinarlo con un try/catch esterno ti permette di aggiungere backoff personalizzato per scenari più complessi.

5. Production tips: HTTPS_PROXY, TLS e parallelismo

Variabili d'ambiente per processi figlio

Se lanci processi figlio (ad esempio curl, python o altri script), imposta $env:HTTPS_PROXY e $env:HTTP_PROXY prima della chiamata:

# Imposta proxy per processi figlio
$env:HTTP_PROXY  = 'http://user-country-US:LA_TUA_PASSWORD@gate.proxyhat.com:8080'
$env:HTTPS_PROXY = 'http://user-country-US:LA_TUA_PASSWORD@gate.proxyhat.com:8080'

# Ora curl eredita il proxy
curl.exe https://httpbin.org/ip

# Pulisci dopo
Remove-Item Env:HTTP_PROXY
Remove-Item Env:HTTPS_PROXY

TLS e SecurityProtocol

In Windows PowerShell 5.1 il protocollo TLS predefinito può essere TLS 1.0, ormai deprecato. Forza TLS 1.2 o 1.3 prima delle richieste:

# Forza TLS 1.2 (necessario in PS 5.1; PS 7 usa di default valori moderni)
[Net.ServicePointManager]::SecurityProtocol = `
    [Net.SecurityProtocolType]::Tls12 -bor `
    [Net.SecurityProtocolType]::Tls13

Secondo i documenti Microsoft su SecurityProtocolType, il valore predefinito dipende dal framework .NET: in .NET 4.6+ è Tls12, ma in ambienti legacy può essere inferiore.

Parallelismo con ForEach-Object -Parallel (PowerShell 7)

Per scraping ad alta concorrenza, PowerShell 7 offre ForEach-Object -Parallel. Ogni thread ha il proprio scope, quindi devi passare le credenziali con $using::

# Scraping parallelo con ForEach-Object -Parallel
$proxyUrl = 'http://gate.proxyhat.com:8080'
$basePass = 'LA_TUA_PASSWORD' | ConvertTo-SecureString -AsPlainText -Force

$urls = 1..20 | ForEach-Object { "https://httpbin.org/ip?n=$_" }

$results = $urls | ForEach-Object -Parallel {
    $page = $_
    $sessionId = "par-$page"
    $user = "user-country-US-session-$sessionId"
    $cred = New-Object System.Management.Automation.PSCredential($user, $using:basePass)

    try {
        $r = Invoke-WebRequest -Uri $page `
            -Proxy $using:proxyUrl -ProxyCredential $cred `
            -UseBasicParsing -TimeoutSec 30
        [PSCustomObject]@{ Url = $page; Status = $r.StatusCode; Ip = ($r.Content | ConvertFrom-Json).origin }
    } catch {
        [PSCustomObject]@{ Url = $page; Status = 'ERR'; Ip = $_.Exception.Message }
    }
} -ThrottleLimit 10

$results | Format-Table -AutoSize

Con -ThrottleLimit 10 mantieni 10 richieste concorrenti: ProxyHat supporta sessioni concorrenti elevate, ma imposta un limite ragionevole per non saturare la larghezza di banda locale.

6. Errori comuni e edge case

• Credenziali con caratteri speciali nel nome utente: se la password contiene @, : o /, usa sempre [pscredential] e non incorporarla nell'URL del proxy.
• Proxy non applicato a Invoke-RestMethod: verifica che -Proxy sia presente: alcuni cmdlet legacy ignorano le variabili d'ambiente in PS 5.1.
• TLS handshake fallito: imposta SecurityProtocol come sopra, oppure passa a PowerShell 7 che usa HttpClient moderno.
• Cookie non persistenti: dimenticare -WebSession $session nelle richieste successive è l'errore più comune.
• Rate limiting 429: usa -MaximumRetryCount e aggiungi Start-Sleep tra le richieste.

Considerazioni etiche e legali

Usare proxy per accedere a dati pubblici è legittimo, ma ci sono limiti importanti:

• Dati pubblici solo: non accedere a contenuti dietro login senza autorizzazione.
• robots.txt: rispetta le direttive Disallow dei siti target.
• CFAA (USA): il Computer Fraud and Abuse Act può applicarsi ad accessi non autorizzati a sistemi protetti. Vedi la guida della FTC.
• GDPR (UE): se raccogli dati personali di utenti UE, assicura conformità al regolamento. Consulta le pagine della Commissione Europea.
• API ufficiali prima: se il sito offre un'API pubblica o a pagamento, usala invece di scrapare HTML.

Tabella comparativa: tipi di proxy ProxyHat

Per la maggior parte dei casi di Invoke-WebRequest proxy e Invoke-RestMethod proxy, i residenziali offrono il miglior rapporto successo/costo. Vedi le locazioni disponibili e il piano tariffario.

Key Takeaways

• Usa -Proxy, -ProxyCredential e -SessionVariable/-WebSession per proxy e sessioni persistenti.
• Codifica geo-targeting e sessioni nel nome utente: user-country-US-session-abc123.
• Forza TLS 1.2+ in PS 5.1 con [Net.ServicePointManager]::SecurityProtocol.
• Usa -MaximumRetryCount e -RetryIntervalSec per retry automatici su 429/503.
• Per concorrenza, ForEach-Object -Parallel in PS 7 con -ThrottleLimit controllato.
• Respetta robots.txt, CFAA e GDPR; preferisci API ufficiali quando disponibili.

Per approfondire, consulta i nostri casi d'uso di web scraping e SERP tracking, oppure la documentazione ProxyHat.