Crawlee Proxy Ayarı: ProxyConfiguration ve Kademeli Proxy

Crawlee proxy ayarı tek bir nesneden geçer: ProxyConfiguration. Bu nesneyi kurar, içine proxy adreslerini verir ve crawler’a proxyConfiguration seçeneğiyle bağlarsınız; o andan sonra crawler’ın açtığı bütün bağlantılar bu adreslerden çıkar. Resmî dokümanın ifadesiyle kurulum üç satırdır: crawlee paketinden ProxyConfiguration içe aktarılır, proxyUrls dizisine adresler yazılır ve nesne crawler’a verilir. Dizide birden fazla adres varsa Crawlee bunları sırayla (round-robin) döndürür; dizideki null değeri “bu sırada proxy kullanma” anlamına gelir.

Rotating gateway kullanan biri için bu dizi çoğu zaman tek elemanlıdır. Gateway zaten her istekte ya da oturum boyunca farklı bir çıkış adresi verdiği için Crawlee tarafında on adreslik bir liste tutmanın anlamı yoktur; tek bir kimlikli adres yeter. Gateway’in kendi içinde nasıl döndüğü ve tek adresin arkasında neden yüzlerce çıkış IP’si olduğu gateway mantığı rehberinde anlatılır; burada yalnız Crawlee’nin o adresi nasıl kullandığıyla ilgileniyoruz.

Adres biçimi, Crawlee’nin kendi örneklerinde http://host biçimindedir; kimlikli gateway için kullanıcı adı ve şifre aynı adresin içine yazılır: http://kullanici:sifre@gateway-adresi:port. RotatingProxy kataloğundaki ürünlerin hepsi HTTP, HTTPS ve SOCKS5 kabul eder; Crawlee örneklerinde HTTP şeması kullanıldığı için başlangıçta HTTP şemalı adresle gidin, hedef HTTPS olsa bile istek proxy’ye CONNECT tüneliyle açılır. Şifrede @ ya da : gibi karakterler varsa bunları URL kodlamasıyla (yüzde işaretli) yazmanız gerekir; aksi hâlde adres yanlış ayrıştırılır ve ilk istek 407 ile döner.

Doküman beş crawler sınıfı için aynı kalıbı gösterir: HttpCrawler, CheerioCrawler, JSDOMCrawler, PlaywrightCrawler ve PuppeteerCrawler. Hepsinde ProxyConfiguration nesnesi kurucu seçeneklerine proxyConfiguration adıyla verilir ve crawler’ın bütün bağlantıları, tarayıcı tabanlı olanlar dahil, o nesneden adres alır. Tarayıcılı crawler’larda da adres aynı nesneden gelir; Playwright’ı Crawlee olmadan kullananların bağlam başına elle yazdığı proxy adımları Scrapy ve Playwright rehberinde ayrı anlatılır.

Kurulumun çalıştığını requestHandler içinden doğrulayabilirsiniz. Handler’a gelen bağlamda proxyInfo adlı bir nesne vardır; dokümana göre url, hostname, port, username, password, isteğe bağlı sessionId ve kademeli kurulumda proxyTier alanlarını taşır. İlk testte requestHandler’da proxyInfo.url ve proxyInfo.sessionId değerlerini loglayın, sonra isteği istemci IP’sini düz metin döndüren bir adrese atın: dönen adres sunucunuzunki değilse gateway devrededir. Bu testi üretim hedefine gitmeden yapmak, 407 ya da tünel hatasını hedef sitenin engeliyle karıştırmanızı önler.

Node.js tarafında istemci kütüphanesini kendiniz yönetiyorsanız (got, axios, undici) proxy ayarı başka bir katmanda yapılır ve o katman Node.js rehberinde işlenir. Crawlee bu kütüphanelerin üstünde bir çerçevedir; proxy, oturum ve yeniden deneme kararlarını sizin yerinize verir. Bu rehberin geri kalanı o kararların nasıl yapıldığını ve gateway’le nasıl çakışmayacağını anlatır.

Crawlee’nin oturum havuzu (SessionPool) çerezleri, hata sayacını ve proxy eşleşmesini bir oturum nesnesinde toplar. Dokümanın tanımıyla ProxyConfiguration.newUrl çağrısına bir sessionId verilirse bir sessionId–proxyUrl çifti oluşturulur ve aynı sessionId ile yapılan sonraki çağrılar hep aynı proxyUrl’yi döndürür; sessionId verilmezse adresler sırayla döner. Crawler içinde bunu siz çağırmazsınız; useSessionPool açıkken (varsayılan değeri true) her istek bir oturuma bağlanır ve o oturumun proxy adresi havuzdan alınır. persistCookiesPerSession seçeneği de varsayılan olarak açıktır: oturumun çerezleri saklanır ve sonraki isteğe otomatik eklenir.

Rotating gateway ile birleştiğinde iki katmanlı bir rotasyon ortaya çıkar ve ikisinin birbirini bozmaması gerekir. Crawlee’nin katmanı proxy adresi seviyesindedir: tek gateway adresi verdiyseniz bütün oturumlar aynı adresi alır, Crawlee tarafında “farklı oturum, farklı proxy” diye bir şey olmaz. Çıkış IP’sini belirleyen katman gateway’in kendisidir. Gateway istek başına rotasyon modundaysa Crawlee’nin oturumu aynı kalsa bile her istek başka adresten çıkar; oturum çerezleri korunur ama hedefin gördüğü IP her seferinde değişir. Çerez ile IP’nin birlikte sabit kalması gereken hedeflerde (sepet, sayfalama, giriş sonrası liste) bu düzen çalışmaz.

Çözüm, oturum kimliğini gateway’e taşımaktır. Oturum nesnesinin id alanı dokümanda “proxy oturum adı olarak kullanılır” diye tanımlanır. newUrlFunction (aşağıda) sessionId parametresini alır; bu fonksiyonun içinde gateway’in kullanıcı adına panelde tanımlı sözdizimiyle oturum kimliğini ekleyip adresi döndürürseniz, Crawlee’nin her oturumu gateway tarafında da ayrı bir sticky oturuma denk gelir. Böylece Crawlee oturumu emekliye ayırıp yenisini açtığında gateway de yeni bir çıkış adresi verir; iki katman aynı sinyali izler. Gateway’in oturum sözdizimi ürüne göre panelde yazar; bu rehber genel bir kalıp vermez.

Havuz boyutu ve oturum ömrü dokümandaki varsayılanlarla başlar: maxPoolSize 1000, bir oturumun en fazla kullanım sayısı (maxUsageCount) 50, ömrü (maxAgeSecs) 3000 saniye. Gateway’deki sticky oturumun süresi bundan kısaysa Crawlee oturumu hâlâ geçerli sayarken çıkış IP’si değişmiş olur. maxAgeSecs değerini gateway’in oturum penceresinden kısa tutun; pencere kısaysa Crawlee tarafını sessionPoolOptions içindeki sessionOptions ile ona göre düşürün.

tieredProxyUrls seçeneği dizi dizisi alır; her iç dizi bir katmandır ve katmanlar ucuzdan pahalıya sıralanır. Dokümandaki örnek dört katmanlıdır: önce proxy’siz (null), sonra orta bir proxy, sonra daha iyi iki proxy, en sonda pahalı bir proxy. Davranış şöyle tarif edilir: her şey yolundaysa bütün istekler ilk katmandan gider; crawler belirli bir alan adında mevcut katmanla sorun yaşadığında o alan adı için bir üst katmana geçer; alt katmanları aralıklarla yoklar ve açılmışlarsa geri iner. Yani geçiş alan adı bazındadır ve kalıcı değildir.

RotatingProxy kataloğunda bu katmanlar iki ürüne denk gelir. Birinci katman IPv4 datacenter: 10 GB paketi 6 USD. İkinci katman IPv4 residential: 10 GB paketi 12 USD. İkisi de GB bazlıdır ve süre sınırı yoktur. Kademeli düzende datacenter adresi birinci iç diziye, residential adresi ikinci iç diziye yazılır; hedeflerin çoğu datacenter katmanından sorunsuz geçer ve residential GB’si yalnız datacenter’ın takıldığı alan adlarında harcanır. Hangi hedef tipinin hangi havuzda takıldığı üç havuz karşılaştırmasında anlatılır; kademe burada o kararı otomatik hâle getirir.

İki uyarı dokümandan birebir aktarılmalı. Birincisi: tieredProxyUrls yalnız crawler örneği üzerinden çalışır; ProxyConfiguration.newUrl çağrısını doğrudan kullanırsanız kademe mantığı işlemez, çünkü engel sinyalini crawler üretir. İkincisi: dokümanda “engellenmeyi tanır” denir ama hangi sinyallerin sayıldığı o sayfada yazmaz; oturum havuzunun engellenmiş kabul ettiği durum kodları (aşağıda) bu kararın bilinen parçasıdır. Kademenin düşüşte hemen inmediğini de hesaba katın: üst katmana geçen alan adı bir süre orada kalır ve residential GB’si o süre boyunca harcanır.

Kota etkisi şöyle hesaplanır, varsayımlar açık: 100.000 sayfalık bir iş, sayfa başına 150 KB, toplam yaklaşık 15 GB olsun. Tek katmanlı residential düzende 15 GB residential tüketilir. Kademeli düzende alan adlarının onda biri residential katmana çıkıyorsa yaklaşık 13,5 GB datacenter ve 1,5 GB residential harcanır. İki ürünün GB fiyatları ürün sayfasında paket paket yazar; hesabı o fiyatlarla kendi hedef dağılımınıza göre yapın. Kota rehberi, GB bazlı ürünlerde paket büyüklüğünün nasıl seçileceğini ayrıca anlatır.

Liste ya da kademe yetmediğinde adresi kendiniz üretirsiniz. newUrlFunction iki parametre alır: sessionId ve içinde request bulunan bir options nesnesi. Dizge olarak proxy adresi ya da “proxy kullanma” anlamında null döndürür; asenkron da olabilir. Dokümandaki örnek, belirli bir alan adını proxy’siz geçirip diğer her şeyi tek proxy’den gönderir. Önemli uyarı aynı sayfadadır: request nesnesi her çağrıda gelmez (örneğin newUrl doğrudan çağrıldığında), bu yüzden fonksiyon request yokken de makul bir varsayılan döndürmelidir.

Rotating gateway ile üç kullanım öne çıkar. Birincisi, yukarıda anlatılan oturum eşlemesi: sessionId’yi gateway kullanıcı adındaki oturum alanına yazmak. İkincisi, ülkeye göre adres: hedef URL’nin alan adı ya da request.userData içindeki pazar bilgisine göre gateway’in ülke parametresi değiştirilir; ülke havuzunun daralmasının rotasyonu nasıl etkilediği ülke ve lokasyon rehberinde anlatılır. Üçüncüsü, kendi sunucularınıza ya da sitemap ve robots.txt gibi hafif isteklere proxy’siz gitmek; bu, GB sayacını gereksiz yere çalıştırmamanın en kolay yoludur.

Üç seçenek birbirini dışlar: Python dokümanı proxy_urls, tiered_proxy_urls ve new_url_function seçeneklerinden tam olarak birinin verilmesi gerektiğini yazar; Node.js tarafında da ProxyConfigurationOptions arayüzünde üçü ayrı alanlardır ve amaçları çakışır. Kademe ile oturum eşlemesini birlikte istiyorsanız kademe kararını newUrlFunction içinde kendiniz vermeniz gerekir: alan adı başına hata sayacı tutup eşik aşılınca residential adresi döndürmek gibi. Bu durumda Crawlee’nin otomatik kademe mantığından vazgeçmiş olursunuz.

Crawlee hatayı iki seviyede ele alır: istek ve oturum. İstek seviyesinde maxRequestRetries kaç kez yeniden deneneceğini belirler; Python dokümanı bu sayacın oturum rotasyonundan kaynaklanan tekrarları kapsamadığını ve oturum rotasyonlarının ayrı bir sınırla (max_session_rotations) sayıldığını yazar. Oturum seviyesinde ise üç yöntem vardır: markBad hata puanını bir artırır (zaman aşımı gibi geçici hatalar için), markGood başarıda puanı errorScoreDecrement kadar (varsayılan 0,5) düşürür, retire oturumu engellenmiş sayıp havuzdan atar. Hata puanı maxErrorScore (varsayılan 3) değerine ulaşan oturum da engellenmiş kabul edilir.

Hangi durum kodunun engel sayıldığı SessionPoolOptions içindeki blockedStatusCodes ile tanımlıdır ve varsayılanı 401, 403 ve 429’dur; bu kodlardan birini alan isteğin oturumu emekliye ayrılır. Dokümanın tavsiyesi nettir: 403 gibi “bu oturum yüzünden” olduğundan emin olduğunuz durumlarda retire, 5xx gibi sunucu kaynaklı hatalarda markBad kullanın. Rotating gateway ile çalışırken 407 ayrı bir sınıftır: proxy kimlik doğrulaması başarısızdır, hedefle ilgisi yoktur, oturumu yenilemek işe yaramaz. 407 ve tünel hatalarının ayrıştırılması bağlantı sorunları rehberinde adım adım verilir.

429 için varsayılan davranışın yan etkisini bilin: Crawlee 429’u engel sayıp oturumu atar ve yeni oturumla devam eder. Gateway oturum eşlemesi yaptıysanız yeni oturum yeni bir çıkış IP’si demektir ve hedefin IP başına koyduğu hız sınırı yeni adresle yeniden başlar. Bu, hedefin sınırını adres değiştirerek aşmak anlamına gelir ve bu rehberin önerdiği bir şey değildir; 429 aldığınızda doğru tepki aynı IP ile temponun düşürülmesidir. Bunu Crawlee’de blockedStatusCodes listesinden 429’u çıkarıp maxConcurrency’yi düşürerek ve Retry-After başlığına uyarak yaparsınız; bekleme sürelerinin nasıl kurulacağı yeniden deneme rehberinde anlatılır.

Gövdeye bakmadan karar vermeyin. 200 ile dönen onay ekranı, boş iskelet ya da doğrulama ara sayfası durum koduyla yakalanmaz; dokümandaki örnekler de requestHandler içinde başlığa ya da gövdedeki bir ifadeye bakıp emin olunca retire, emin olunmayınca markBad çağırır. Bu kontrolün sayfa tipine göre nasıl yazılacağı yanıt doğrulama rehberinde işlenir. Crawlee’de BasicCrawler başarılı istekte markGood’u sizin yerinize çağırır; sizin işiniz “başarılı görünen ama boş” yanıtı yakalayıp hata saydırmaktır.

Python sürümünde aynı kavramlar snake_case adlarla gelir: ProxyConfiguration kurucusu proxy_urls, new_url_function ve tiered_proxy_urls alır ve bunlardan tam olarak biri verilmelidir. Crawler’a bağlama proxy_configuration parametresiyle yapılır; oturum havuzu use_session_pool ile açılır, isteğe bağlı olarak özel bir session_pool verilir. Yeniden deneme sınırı max_request_retries, oturum rotasyonu sınırı max_session_rotations adını taşır. Python ProxyInfo nesnesi Node.js’tekine ek olarak scheme alanı içerir ve session_id açıklamasında “aynı oturum kimliği aynı proxy adresini garanti eder” ifadesi geçer.

Oturum yöntemleri Python’da retire, mark_bad ve mark_good’dur; Node.js’teki retireOnBlockedStatusCodes yönteminin Python’da birebir karşılığı yoktur, onun yerine is_blocked_status_code adlı bir denetim ve Session kurucusunda blocked_status_codes listesi vardır. Python dokümanı bu liste için varsayılan değer yazmaz; engel sayılacak kodları kendiniz vermeniz daha güvenlidir. Varsayılanlar Python oturumunda max_age 50 dakika, max_error_score 3,0, error_score_decrement 0,5 ve max_usage_count 50’dir.

Kademeli proxy Python dokümanında “crawler engellenmenin olmadığı en düşük indeksli katmanı otomatik olarak kullanmaya çalışır” diye tarif edilir; Node.js dokümanındaki alan adı bazlı geçiş ve geri iniş ayrıntısı Python sayfasında yazmaz. Python’da kademe davranışını üretime almadan önce iki alan adıyla küçük bir deneme yapıp proxy_tier alanının gerçekten değiştiğini loglayın. Üçüncü taraf blog yazılarında geçen ve resmî dokümanda bulunmayan seçenek adlarını (ör. istek sayısına göre döndürme ayarı) kullanmayın; mevcut API’de böyle bir seçenek yoktur, rotasyon gateway’in işidir.

Crawlee’de proxy kullanıcı adı ve şifresi nereye yazılır? Proxy adresinin içine: proxyUrls dizisindeki adres http://kullanici:sifre@gateway:port biçiminde yazılır; ayrı bir kimlik alanı yoktur. Şifredeki özel karakterler URL kodlamasıyla kaçırılır. Değeri koda gömmek yerine ortam değişkeninden okuyup adresi çalışma zamanında kurun.

Crawlee kendi rotasyonunu yapıyorsa rotating gateway’e yine gerek var mı? Crawlee proxy adresi listesini döndürür, IP üretmez. Elinizde yüzlerce sabit proxy adresi yoksa liste tek elemanlı kalır ve rotasyonu gateway yapar. Gateway tek adresin arkasında havuzu yönetir; Crawlee ise oturum, çerez ve hata kararlarını verir. İkisi farklı katmandır ve birlikte kullanılır.

Kademeli proxy GB tüketimini nasıl etkiler? Katmanlar ucuzdan pahalıya sıralandığında pahalı katmanın GB’si yalnız ucuz katmanın takıldığı alan adlarında harcanır. Kataloğa göre IPv4 datacenter 10 GB 6 USD, IPv4 residential 10 GB 12 USD; hedeflerin büyük kısmı datacenter’dan geçiyorsa toplam maliyet tek katmanlı residential düzene göre düşer. Üst katmana çıkan alan adının bir süre orada kaldığını ve o sürede residential GB harcandığını hesaba katın.

Bir oturum hep aynı IP’de mi kalır? Crawlee tarafında aynı sessionId aynı proxy adresini alır; ama çıkış IP’sini gateway belirler. Gateway istek başına modundaysa adres aynı kalsa da IP her istekte değişir. IP’nin oturum boyunca sabit kalması için sessionId’yi newUrlFunction ile gateway’in oturum parametresine yazın ve Crawlee oturum ömrünü gateway’in sticky penceresinden kısa tutun.

Crawlee Python sürümünde aynı ayarlar var mı? Evet, snake_case adlarla: proxy_urls, new_url_function, tiered_proxy_urls; crawler’da proxy_configuration, use_session_pool, max_request_retries ve max_session_rotations. Node.js’teki retireOnBlockedStatusCodes yerine is_blocked_status_code ve blocked_status_codes vardır ve engel kodlarının varsayılanı Python dokümanında yazmaz; listeyi kendiniz verin.