पुपेटियर फाइल डाउनलोड: नोड.जेएस डेवलपर्स के लिए एक संपूर्ण गाइड

TL;DR:

• हेडलैस क्रोम में डाउनलोड्स एक सीडीपी समस्या है, न कि पप्पेटियर-एपीआई समस्या। पप्पेटियर का कोई पहले वर्ग का page.download() नहीं है; आप Browser.setDownloadBehavior के साथ सीधे क्रोम डेवलपर टूल प्रोटोकॉल को नियंत्रित करते हैं और Browser.downloadProgress के लिए सुनते हैं।
• allowAndName और eventsEnabled वह संयोजन है जो वास्तव में पूर्णता की रिपोर्ट करता है। केवल व्यवहार सेट करना "फाइल सहेजें" संवाद को चुप कर देता है; घटनाओं को चालू करना आपको समाप्त हुए बाइट्स की गिनती के लिए await करने देता है न कि निश्चित सोने के साथ अनुमान लगाने के लिए।
• एक क्लाउड ब्राउज़र पर फाइल सर्वर-साइड पर रहती है — इसलिए आप पृष्ठ के माध्यम से बाइट्स को वापस लाते हैं। page.evaluate() के अंदर एक समान-मूल fetch() फ़ाइल को बेस64 के रूप में लौटाता है, जिसे आप डिकोड करते हैं और स्थानीय डिस्क पर लिखते हैं। कोई हेडफुल मशीन नहीं है, कोई साझा वॉल्यूम नहीं है।
• एंटी-बॉट और भौगोलिक-गेटिंग भी डाउनलोड पर लागू होते हैं। कई गेटेड फाइलें केवल सही देश में एक आवासीय आईपी के लिए सेवा करती हैं; proxyCountry के साथ आउटगोइंग को पिन करना डाउनलोड को सफल बनाने का एक हिस्सा है।
• पूरा प्रवाह स्क्रेपलेस स्क्रेपिंग ब्राउज़र पर एक Puppeteer.connect() कॉल के साथ चलता है। क्लाउड ब्राउज़र सत्र को उत्पन्न करता है, एंटी-डिटेक्शन फ़िंगरप्रिंटिंग लागू करता है, और पप्पेटियर को एक मानक वेबसॉकेट एंडपॉइंट प्रदान करता है — आपका डाउनलोड कोड वहां से शुद्ध सीडीपी है।
• शुरू करने के लिए मुक्त। नए स्क्रेपलेस खातों में मुफ्त स्क्रेपिंग ब्राउज़र रनटाइम शामिल है — app.scrapeless.com पर साइन अप करें।

परिचय: "पप्पेटियर के साथ एक फ़ाइल डाउनलोड करना" क्यों कठिन है

पप्पेटियर नोड.जेएस डेवलपर्स को क्रोम पेज पर पूर्ण नियंत्रण देता है — क्लिक करना, टाइप करना, DOM पढ़ना। फ़ाइल डाउनलोड एक ऐसा सामान्य कार्य है जिसके लिए इसका कोई समर्पित तरीका नहीं है। await page.download(selector) नहीं है। एक डिफ़ॉल्ट हेडलैस सत्र में डाउनलोड लिंक पर क्लिक करना दो असहायक चीजों में से एक करता है: नेविगेशन निगल लिया जाता है, या क्रोम ट्रांसफर को ब्लॉक कर देता है क्योंकि कोई डाउनलोड निर्देशिका कॉन्फ़िगर नहीं की गई है।

वास्तविक नियंत्रण एक परत नीचे है, क्रोम डेवलपर टूल प्रोटोकॉल (सीडीपी) में। Browser.setDownloadBehavior क्रोम को बताता है कि फ़ाइलें कहाँ जाती हैं और क्या उन्हें अनुमति दी जानी चाहिए; Browser.downloadWillBegin और Browser.downloadProgress जीवनचक्र की रिपोर्ट करते हैं ताकि आप सटीक क्षण की प्रतीक्षा कर सकें जब एक फ़ाइल समाप्त हो जाती है न कि सोने और उम्मीद करने के।

अपने स्वयं के मशीन पर इसे चलाएँ और आपको अभी भी दो समस्याएँ हैं जो सीडीपी से संबंधित नहीं हैं: लक्षित साइट हेडलेस क्रोम को एक बॉट के रूप में फ़्लैग करती है, और गेटेड फ़ाइलें अक्सर कुछ भी अस्वीकार कर देती हैं जो अपेक्षित क्षेत्र में आवासीय आईपी नहीं है। यह मार्गदर्शिका स्क्रेपलेस स्क्रेपिंग ब्राउज़र के शीर्ष पर पूरे प्रवाह को चलाती है - एक एंटी-डिटेक्शन क्लाउड ब्राउज़र जो सत्र को उत्पन्न करता है, आवासीय आउटगोइंग लागू करता है, और पप्पेटियर को एक सामान्य वेबसॉकेट एंडपॉइंट प्रदान करता है। डाउनलोड कोड शुद्ध सीडीपी रहता है; पहचान और भौगोलिक समस्याएँ रनटाइम द्वारा संभाली जाती हैं। एक मोड़ है जो एक क्लाउड ब्राउज़र जोड़ता है - फ़ाइल सर्वर-साइड पर डाउनलोड होती है - और इस मार्गदर्शिका का दूसरी आधा दिखाता है कि उन बाइट्स को आपके स्थानीय डिस्क पर वापस लाने का पैटर्न क्या है।

इसके साथ आप क्या कर सकते हैं

• एक लॉगिन के पीछे रिपोर्ट, एक्सपोर्ट और स्टेटमेंट खींचें — चालान पीडीएफ, CSV एक्सपोर्ट, डेटा-रूम फ़ाइलें — जब सत्र को प्रमाणित किया जाता है।
• निर्मित फ़ाइलों को कैप्चर करें जो एक पृष्ठ एक ब्लॉब से क्लाइंट-साइड बनाता है (चार्ट एक्सपोर्ट, "CSV डाउनलोड करें" बटन) और कभी भी एक स्थिर यूआरएल के रूप में मौजूद नहीं होती हैं।
• गेटेड दस्तावेज़ों को पकड़ें जो केवल एक विशिष्ट देश में एक आवासीय आईपी को सेवा करते हैं, अनुरोध से पहले आउटगोइंग को पिन करके।
• निर्धारित रूप से प्रतीक्षा करें एक ट्रांसफर समाप्त होने के लिए downloadProgress का उपयोग करके न कि एक नाजुक निश्चित विलंब के साथ।
• समान स्क्रिप्ट का पैमाना कई फ़ाइलों या खातों के साथ बिना हेडफुल मशीनें खड़ी किए — ब्राउज़र दूरस्थ है।

क्यों स्क्रेपलेस स्क्रेपिंग ब्राउज़र

स्क्रेपलेस स्क्रेपिंग ब्राउज़र एक अनुकूलन योग्य, एंटी-डिटेक्शन क्लाउड ब्राउज़र है जो वेब क्रॉलर्स और एआई एजेंटों के लिए डिज़ाइन किया गया है। विशेष रूप से पप्पेटियर डाउनलोड के लिए, यह लाता है:

• एक मानक पप्पेटियर कनेक्शन — Puppeteer.connect() एक सामान्य Browser ऑब्जेक्ट लौटाता है, इसलिए हर सीडीपी कॉल जो आप पहले से जानते हैं वो बिना बदलाव के काम करती है।
• 195+ देशों में आवासीय प्रॉक्सीज़ — इस प्रकार के गेटेड फ़ाइलों को एक आईपी पर सेवा देने के लिए proxyCountry पिन करें जिसे वे भरोसा करते हैं।
• क्लाउड-साइड एंटी-डिटेक्शन फ़िंगरप्रिंटिंग — सत्र असली ब्राउज़र की तरह दिखता है, इसलिए डाउनलोड लिंक वास्तव में पेश किया जाता है न कि बॉट दीवार के पीछे छिपा होता है।
• सत्र निरंतरता — नेविगेशनों के पार कुकीज़ और प्रमाणन स्थिति को गर्म रखें, जो लॉग इन डाउनलोड संभव बनाता है।
• स्व-विकसित क्रोमियम — पूरी सीडीपी सतह, इसलिए Browser.setDownloadBehavior और डाउनलोड घटनाएँ ठीक उसी तरह कार्य करती हैं जैसे दस्तावेज में वर्णित है।

app.scrapeless.com पर स्वतंत्र योजना पर अपना एपीआई कुंजी प्राप्त करें।

पूर्वापेक्षाएँ

• Node.js 18 या नया
• एक स्क्रेपलेस खाता और एपीआई कुंजी — app.scrapeless.com पर साइन अप करें
• पप्पेटियर और async/await के साथ बुनियादी परिचय

इंस्टॉल

1. एसडीके और पप्पेटियर जोड़ें

स्क्रेपलेस एसडीके क्लाउड सत्र को मिंट करता है और इसे पप्पेटियर से जोड़ता है। आपको puppeteer-core (बिना बंडल्ड क्रोमियम के प्रोटोकॉल क्लाइंट — ब्राउज़र दूरस्थ है) की आवश्यकता है:

npm install @scrapeless-ai/sdk puppeteer-core

2. अपना एपीआई कुंजी सेट करें

इसे वातावरण से पढ़ें; इसे कभी हार्डकोड न करें:

export SCRAPELESS_API_KEY="your_api_token_here"

कॉन्फ़िगर करें: पप्पेटियर को क्लाउड ब्राउज़र से जोड़ें

Puppeteer.connect() एक स्क्रेपलेस सत्र बनाता है और एक मानक पप्पेटियर Browser लौटाता है। यहां प्रॉक्सी देश को पिन करें ताकि हर अनुरोध — डाउनलोड सहित — उस क्षेत्र से निकल सके जिसे आप चाहते हैं:

import { Puppeteer } from '@scrapeless-ai/sdk';

const browser = await Puppeteer.connect({
  apiKey: process.env.SCRAPELESS_API_KEY,
  sessionName: 'puppeteer-downloads',
  proxyCountry: 'US',
  sessionTTL: 300, // सेकंड में सत्र जीवित रहता है
});

const page = await browser.newPage();

यहां से, browser और page साधारण पप्पेटियर ऑब्जेक्ट हैं। नीचे सब कुछ मानक सीडीपी है।

बुनियादी कार्यान्वयन: डाउनलोड व्यवहार सेट करें और पूर्णता की प्रतीक्षा करें

दो सीडीपी कॉल हैं जो मायने रखते हैं और एक इवेंट है जिस पर आप प्रतीक्षा करते हैं:

1. Browser.setDownloadBehavior जिसमें behavior: 'allowAndName' डाउनलोड की अनुमति देता है और सर्वर साइड पर फ़ाइल का नाम रखता है। eventsEnabled: true वह हिस्सा है जिसे अधिकांश गाइड छोड़ देते हैं — इसके बिना, कोई प्रगति रद्दीकरण नहीं होता है और आप सोने के लिए वापस आ जाते हैं।
2. Browser.downloadWillBegin आपको बताता है कि एक ट्रांसफ़र शुरू हुआ, जिसमें suggestedFilename और guid है।
3. Browser.downloadProgress inProgress → completed (या canceled) की रिपोर्ट करता है, जिसमें receivedBytes और totalBytes होते हैं।

const cdp = await page.createCDPSession();

await cdp.send('Browser.setDownloadBehavior', {
  behavior: 'allowAndName',
  downloadPath: '/tmp/downloads',
  eventsEnabled: true,
});

// केवल तब समाप्त करें जब ट्रांसफर वास्तव में पूरा हो जाए
const downloadComplete = new Promise((resolve) => {
  let meta = {};
  cdp.on('Browser.downloadWillBegin', (e) => {
    meta = { filename: e.suggestedFilename, guid: e.guid };
  });
  cdp.on('Browser.downloadProgress', (e) => {
    if (e.state === 'completed') {
      resolve({ ...meta, totalBytes: e.totalBytes });
    }
  });
});

अब डाउनलोड को ट्रिगर करें — बटन पर क्लिक करना, एक लिंक, या, जैसा कि यहाँ है, एक फ़ाइल जो पृष्ठ क्लाइंट-साइड बनाता है — और प्रॉमिस का इंतजार करें:

await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });

// "डाउनलोड CSV" बटन जो ब्राउज़र में एक बबल से फ़ाइल बनाता है
await page.evaluate(() => {
  const blob = new Blob(['col1,col2\n1,2\n3,4\n'], { type: 'text/csv' });
  const a = document.createElement('a');
  a.href = URL.createObjectURL(blob);
  a.download = 'report.csv';
  document.body.appendChild(a);
  a.click();
});

const result = await downloadComplete;
console.log(result);
// { filename: 'report.csv', guid: '845c9455-…', totalBytes: 18 }

प्रॉमिस उस क्षण में हल हो जाती है जब state === 'completed' आता है — कोई निश्चित नींद नहीं, और आपको असली बाइट संख्या वापस मिलती है।

अपने एपीआई कुंजी को मुफ्त योजना पर प्राप्त करें: app.scrapeless.com

क्लाउड ट्विस्ट: बाइट्स को अपने स्थानीय डिस्क पर लाना

एक स्थानीय हेडफुल रन पर, allowAndName फ़ाइल को आपके downloadPath पर लिखता है और आप इसे डिस्क से पढ़ते हैं। एक क्लाउड ब्राउज़र पर फ़ाइल दूरस्थ सत्र पर आती है, आपकी मशीन पर नहीं — इसलिए downloadPath सर्वर-साइड है और आपका स्थानीय /tmp/downloads खाली रहता है।

विश्वसनीय पैटर्न यह है कि फ़ाइल के बाइट्स को पृष्ठ संदर्भ के अंदर लाया जाए और उन्हें बेस64 के रूप में वापस लौटाया जाए, फिर उन्हें स्थानीय स्तर पर डिकोड और लिखा जाए। एक नियम: fetch() same-origin policy के अधीन है, इसलिए पहले फ़ाइल की अपनी उत्पत्ति पर जाएं, फिर इसे लाएं:

import { writeFileSync } from 'node:fs';

const fileUrl = 'https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf';

// फ़ाइल की उत्पत्ति पर उतरें ताकि fetch() समान-उत्पत्ति हो (कोई CORS ब्लॉक न हो)
await page.goto(new URL(fileUrl).origin, { waitUntil: 'domcontentloaded' });

const out = await page.evaluate(async (url) => {
  const res = await fetch(url);
  const bytes = new Uint8Array(await res.arrayBuffer());
  let binary = '';
  for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
  return {
    status: res.status,
    type: res.headers.get('content-type'),
    b64: btoa(binary),
  };
}, fileUrl);

const buffer = Buffer.from(out.b64, 'base64');
writeFileSync('./dummy.pdf', buffer);
console.log({ status: out.status, type: out.type, bytes: buffer.length });
// { status: 200, type: 'application/pdf; qs=0.001', bytes: 13264 }

क्योंकि फ़ेच प्रमाणीकरण पृष्ठ के अंदर चलती है, यह सत्र के कुकीज़ को ले जाती है - इसलिए लॉगिन के पीछे के फ़ाइलें ठीक उसी तरह डाउनलोड होती हैं जैसे कि एक के सामने। CDP-ईवेंट दृष्टिकोण और यह फ़ेच दृष्टिकोण पूरक हैं: यह जानने के लिए ईवेंट का उपयोग करें कि कब एक क्लिक-प्रेरित ट्रांसफर समाप्त हुआ; जब आपके पास फ़ाइल का URL हो और आप बाइट्स को स्थानीय रूप से वापस चाहते हों, तो इन-पृष्ठ फ़ेच का उपयोग करें।

उन्नत पैटर्न

गेटेड फ़ाइलों के लिए आउटगोइंग को पिन करें। यदि कोई दस्तावेज़ केवल एक क्षेत्र के लिए है, तो कनेक्ट समय पर proxyCountry निर्धारित करें। डाउनलोड तब उस निवासीय आईपी को विरासत में ले लेगा - बिना प्रति-निवेदन प्रॉक्सी juggling के।

प्रमाणित करें, फिर डाउनलोड करें। लॉगिन प्रवाह और डाउनलोड के लिए एक ही पृष्ठ (और इसलिए एक ही सत्र और कुकीज़) बनाए रखें। स्क्रैपलेस सत्र स्थिरता नेवीगेशन के माध्यम से प्रमाणीकरण की स्थिति को गर्म रखती है, इसलिए ऊपर का इन-पृष्ठ फ़ेच एक लॉगिन किया हुआ संदर्भ देखता है।

बड़े फ़ाइलों के लिए प्रगति पढ़ें। Browser.downloadProgress भी state: 'inProgress' और एक बढ़ता हुआ receivedBytes के साथ सक्रिय होता है। वास्तविक प्रगति बार को सतह पर लाने के लिए totalBytes के खिलाफ अनुपात को लॉग करें, न कि स्पिनर।

कार्य पूरा होने पर सत्र बंद करें। await browser.close() तुरंत क्लाउड सत्र को समाप्त करता है ताकि आप रनटाइम को न पकड़ें जिसका आप उपयोग नहीं कर रहे हैं।

समस्या निवारण

निष्कर्ष: आपके पाइपलाइन में डाउनलोड पहले श्रेणी के चरण के रूप में

Puppeteer के साथ फ़ाइल डाउनलोड करना तीन मूव्स पर निर्भर करता है: Chrome को डाउनलोड की अनुमति और रिपोर्ट करने के लिए बताना (Browser.setDownloadBehavior के साथ eventsEnabled), वास्तविक पूर्णता ईवेंट का इंतजार करना (Browser.downloadProgress), और - एक क्लाउड ब्राउज़र पर - बाइट्स को एक ही मूल के इन-पृष्ठ फ़ेच के माध्यम से वापस खींचना। इसे स्क्रैपलेस स्क्रैपिंग ब्राउज़र पर चलाना उन दो जटिल अंगों को समेटता है जो CDP से संबंधित नहीं हैं - बॉट पहचान और जियो-गेटिंग - को रनटाइम में, इसलिए वही स्क्रिप्ट जो एक सार्वजनिक फ़ाइल पर काम करती है वह भी एक गेटेड, लॉगिन की गई फ़ाइल पर काम करती है। डाउनलोड की ओर ले जाने वाले फॉर्म-ड्रिवन प्रवाह के लिए, इसे Scrapling क्लाउड-ब्राउज़र गाइड के साथ जोड़ें, और पूर्ण CDP सतह के लिए Scraping Browser उत्पाद पृष्ठ और दस्तावेज़ देखें। आउटगोइंग को पिन करें, प्रमाणीकरण की गई फ़ाइलों के लिए सत्र को गर्म रखें, और नींद के बजाय completed का इंतजार करें।

क्या आप अपनी एआई-संचालित डेटा पाइपलाइन बनाने के लिए तैयार हैं?

हमारे समुदाय से जुड़ें, एक मुफ्त योजना का दावा करें और डाउनलोड और निष्कर्षण पाइपलाइनों का निर्माण कर रहे डेवलपर्स से जुड़े: Discord · Telegram।

app.scrapeless.com पर मुफ्त स्क्रैपिंग ब्राउज़र रनटाइम के लिए साइन अप करें और अपने कार्यप्रवाह की आवश्यकताओं के अनुसार ऊपर दिए गए पैटर्न को फ़ाइलों, क्षेत्रों और लॉगिन में अनुकूलित करें। पैमाने के लिए मूल्य निर्धारण देखें।

अक्सर पूछे जाने वाले प्रश्न

प्रश्न: क्या Puppeteer में अंतर्निहित डाउनलोड विधि है?
नहीं। कोई page.download() नहीं है। आप Browser.setDownloadBehavior के साथ Chrome डेवलपर टूल प्रोटोकॉल के माध्यम से डाउनलोड कॉन्फ़िगर करते हैं और उन्हें Browser.downloadWillBegin और Browser.downloadProgress ईवेंट्स के साथ देखते हैं।

प्रश्न: क्या मुझे फ़ाइलें डाउनलोड करने के लिए प्रॉक्सी की आवश्यकता है?
सार्वजनिक फ़ाइलों के लिए, अनिवार्य रूप से नहीं। क्षेत्रों द्वारा गेटेड फ़ाइलों या केवल निवासीय आईपी के लिए दी गई फ़ाइलों के लिए, हाँ - कनेक्ट समय पर proxyCountry पिन करें ताकि ट्रांसफर एक आईपी से बाहर जाए जिसे साइट विश्वसनीय मानती है।

प्रश्न: क्लाउड ब्राउज़र पर चलाते समय मेरा स्थानीय डाउनलोड निर्देशिका खाली क्यों है?
क्योंकि फ़ाइल आपके मशीन पर नहीं, दूरस्थ सत्र पर डाउनलोड होती है। ऊपर बताए गए अनुसार, page.evaluate() के अंदर फ़ाइल URL को फ़ेच करके बाइट्स को प्राप्त करें और स्थानीय रूप से बेस64 को डिकोड करें।

प्रश्न: मैं एक फ़ाइल कैसे डाउनलोड करूं जो लॉगिन के पीछे है?
पहले उसी पृष्ठ पर प्रमाणीकरण करें, फिर इन-पेज fetch() चलाएँ - यह सत्र कुकीज़ को ले जाता है, इसलिए फ़ाइल लॉग इन किए गए उपयोगकर्ता के रूप में डाउनलोड होती है। Scrapeless सत्र स्थिरता ने उस प्रमाणीकरण स्थिति को नेविगेशनों के बीच बनाए रखा है।

प्रश्न: क्या मैं टाइमआउट का अनुमान लगाने के बजाय डाउनलोड समाप्त होने का इंतजार कैसे करूँ?
Browser.downloadProgress के लिए सुनें और तब समाधान करें जब state === 'completed'। यह घटना receivedBytes और totalBytes को शामिल करती है, इसलिए आप वास्तविक प्रगति का प्रदर्शन भी कर सकते हैं।

प्रश्न: क्या मैं बिना किसी एआई एजेंट या अतिरिक्त उपकरणों के यह चला सकता हूँ?
हाँ। यह साधारण Puppeteer है जिसे Scrapeless सत्र पर CDP के ऊपर चलाया जाता है - कोई एजेंट की आवश्यकता नहीं है। SDK केवल कनेक्शन बनाता है।