كيف أشغّل Playwright في السحابة؟
- شغّل متصفحًا. يشغّل
POST /v1/agents(أوcreate_agent()في SDK) متصفح Phantom في سحابة Browsa ويُرجعidالخاص به، وعنوانcdp_http، وlive_urlيمكنك فتحه لمشاهدته. - اتصل. استبدل
chromium.launch()بـchromium.connect_over_cdp(cdp_http, headers={"X-API-Key": API_KEY})، أوpuppeteer.launch()بـpuppeteer.connect({ browserURL, headers }). المتصفح يأتي بسياق وصفحة مفتوحة: استخدمهما. - نظّف. استدعِ
destroy_agent()عند الانتهاء، أو دع المتصفح يُغلق عند انتهاء مدة TTL. تدفع 1 رصيد لكل 12 دقيقة بدأت من تشغيله، ويعود باقي ما حُجز.
تحتاج إلى مفتاح Browsa API (يبدأ بـ agt_live_). أنشئ حسابًا لتحصل على 100 رصيد مجاني عند تأكيد بريدك الإلكتروني، بلا بطاقة. لا حاجة إلى تثبيت Chrome على جهازك أو في صورة Docker.
اربط عميلك
Playwright في Python
pip install browsa playwrightلا تحتاج إلى playwright install: المتصفح يعمل على Browsa.
import os
from browsa import Client
from playwright.sync_api import sync_playwright
API_KEY = os.environ["BROWSA_API_KEY"]
client = Client(api_key=API_KEY)
agent = client.create_agent(ttl="10m") # a cloud browser, up to 10 minutes
try:
with sync_playwright() as p:
browser = p.chromium.connect_over_cdp(
agent["cdp_http"], headers={"X-API-Key": API_KEY}
)
context = browser.contexts[0]
page = context.pages[0] if context.pages else context.new_page()
page.goto("https://example.com")
print(page.title())
# the rest is plain Playwright
finally:
client.destroy_agent(agent["id"])Playwright في TypeScript أو Node
npm i browsa playwrightimport { Client } from "browsa";
import { chromium } from "playwright";
const apiKey = process.env.BROWSA_API_KEY!;
const client = new Client({ apiKey });
const agent = await client.createAgent({ ttl: "10m" });
try {
const browser = await chromium.connectOverCDP(agent.cdp_http, {
headers: { "X-API-Key": apiKey },
});
const context = browser.contexts()[0];
const page = context.pages()[0] ?? (await context.newPage());
await page.goto("https://example.com");
console.log(await page.title());
} finally {
await client.destroyAgent(agent.id);
}Puppeteer
استخدم puppeteer-core. له واجهة puppeteer نفسها لكنه لا ينزّل متصفحًا، ولم تعد بحاجة إليه.
npm i browsa puppeteer-coreimport { Client } from "browsa";
import puppeteer from "puppeteer-core";
const apiKey = process.env.BROWSA_API_KEY!;
const client = new Client({ apiKey });
const agent = await client.createAgent({ ttl: "5m" });
try {
const browser = await puppeteer.connect({
browserURL: agent.cdp_http,
headers: { "X-API-Key": apiKey },
});
const [page] = await browser.pages();
await page.goto("https://example.com");
console.log(await page.title());
await browser.disconnect();
} finally {
await client.destroyAgent(agent.id);
}CDP المباشر وعملاء آخرون
تتضمن استجابة الإنشاء عنوانين. cdp_http هو نقطة نهاية HTTP للمتصفح، وهي ما يتوقعه Playwright وPuppeteer. وcdp_url هو WebSocket لصفحة واحدة، للعملاء الذين يتحدثون CDP مباشرة. وكلاهما يحتاج إلى مفتاحك في ترويسة X-API-Key. وأي مكتبة تستطيع الاتصال بمتصفح قائم عبر CDP مع ترويسة مخصصة يمكنها استخدام العنوان نفسه، وهكذا يعمل دليلا browser-use وStagehand.
دون SDK، شغّل المتصفح بطلب HTTP عادي:
curl https://browsa.io/v1/agents \
-H "X-API-Key: $BROWSA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"ttl": "10m", "initial_url": "https://example.com"}'
# -> { "id": "agt_…", "status": "running", "cdp_http": "https://browsa.io/api/v1/cdp/…",
# "cdp_url": "wss://browsa.io/api/v1/cdp/…/ws/page/…", "live_url": "…", "cost_credits": 5 }cost_credits هو ما يحجزه المتصفح أثناء تشغيله: 1 رصيد لمدة TTL حتى 5 دقائق، و5 لمدة أطول. وعند انتهائه، تعود إلى رصيدك وحدات الـ12 دقيقة التي لم يستخدمها.
ما الذي يختلف عن المتصفح المحلي؟
حجم العرض ووكيل المستخدم
تُضبط أبعاد الشاشة، ووكيل المستخدم، والمنطقة الزمنية، واللغة، والموقع الجغرافي، وعدد المعالجات معًا عند تشغيل المتصفح. أوامر محاكاة CDP التي تغيّر أحدها وحده تُرجع نجاحًا ولا تغيّر شيئًا، لذا لا أثر لـ page.set_viewport_size() وpage.setViewport() وpage.setUserAgent().
ما العملمرّر screen_resolution وos_type إلى POST /v1/agents. وللتحكم في المحاكاة بنفسك، أضف cdp_overrides=allow إلى استعلام عنوان CDP؛ وحينها يقع عليك الحفاظ على اتساق البصمة.
السياقات والصفحات
يبدأ المتصفح بسياق وصفحة مفتوحة.
ما العملاستخدم browser.contexts[0] وصفحته الأولى بدلًا من إنشاء سياق جديد.
تنزيل الملفات
تبقى الملفات المنزّلة في المتصفح السحابي، ويُبلغ حدث التنزيل في Playwright بالحالة canceled.
ما العملاجلب الملف من داخل الصفحة (انظر أدناه)، فيستخدم ذلك ملفات تعريف الارتباط وعنوان IP الخاصين بالمتصفح.
مدة التشغيل
يعمل المتصفح حتى انتهاء مدة TTL، بحد أقصى ساعة واحدة، أو حتى تدمّره. ولا ينتهي بسبب الخمول.
ما العملاطلب مدة TTL التي تحتاجها (من "5m" إلى "1h"). شغّل متصفحًا جديدًا للمهام الأطول، أو استخدم هوية محفوظة للاحتفاظ بتسجيلات الدخول بينها.
الشبكة
من دون بروكسي، تخرج حركة المرور من مركز بيانات Browsa بعنوان IP لمركز بيانات.
ما العملمرّر شبكة من Browsa في proxy ({"network": "residential"})، أو بروكسي HTTP أو HTTPS أو SOCKS5 الخاص بك، أو بروكسي محفوظًا في proxy_id.
مؤشرات الأتمتة
يفعّل Playwright وPuppeteer نطاق Runtime في CDP عند الاتصال، وبعض فحوصات كشف الروبوتات ترى ذلك.
ما العملإذا رصد موقعٌ عميلك، جرّب عميل CDP مباشرًا دون Runtime.enable، أو وكيل المهام من Browsa (POST /v1/tasks). اطّلع على النتائج المؤرخة في صفحة مقاييس الأداء.
متصفحات متوازية
6 خانات متصفح لكل مساحة عمل. الطلب مع امتلاء كل الخانات يُرجع 429 مع Retry-After: 30 ولا يُحاسَب عليه.
ما العملضع العمل في طابور من جهتك، أو راسل support@browsa.io للحصول على خانات أكثر.
كيف أعيد الاتصال بعد انقطاعه؟
إغلاق اتصال Playwright أو Puppeteer لا يوقف المتصفح، بل يستمر حتى انتهاء مدة TTL، فتستطيع عملية أخرى الاتصال به. احصل على عنوانه مجددًا عبر GET /v1/agents/{id}/cdp (أو get_agent(agent_id) في Python، وgetAgent(agentId) في TypeScript) واتصل بترويسة X-API-Key نفسها. تُرجع نقطة النهاية 409 عندما لا يعود المتصفح قيد التشغيل.
كيف أنزّل ملفًا؟
اجلبه من داخل الصفحة وأعِد البايتات:
import base64
b64 = page.evaluate("""async (url) => {
const buf = new Uint8Array(await (await fetch(url)).arrayBuffer());
let s = ""; for (const b of buf) s += String.fromCharCode(b);
return btoa(s);
}""", "https://example.com/report.pdf")
open("report.pdf", "wb").write(base64.b64decode(b64))كيف أستخدم البروكسي الخاص بي؟
أضف كائن proxy عند تشغيل المتصفح. يستخدم المتصفح حينها عنوان IP للبروكسي، ومع ضبط country تتبع منطقته الزمنية ولغته ذلك البلد. لا تكلّف حركة البروكسي شيئًا إضافيًا على Browsa.
curl https://browsa.io/v1/agents \
-H "X-API-Key: $BROWSA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"ttl": "10m",
"proxy": {"type": "http", "host": "proxy.example.com", "port": 8080,
"username": "your-proxy-user", "password": "your-proxy-password"},
"country": "de"
}'يبدأ المتصفح الخام حتى لو تعذّر الوصول إلى البروكسي، لذا تحقق منه أولًا. البروكسي المحفوظ له نقطة نهاية للفحص ويمكن تمريره في proxy_id.
كيف أحتفظ بتسجيلات الدخول بين التشغيلات؟
استخدم هوية دائمة بدلًا من متصفح مؤقت. تحتفظ الهوية بملفات تعريف الارتباط والتخزين المحلي والبصمة بين الجلسات. أنشئها مرة واحدة بـ "mode": "persistent"، ثم افتح جلسة متى احتاجها سكربت: يُرجع POST /v1/agents/{id}/sessions البنية نفسها لمتصفح جديد، بما فيها cdp_http، وتتصل بها تمامًا كما سبق. تكلف الهوية 50 رصيدًا كل 30 يومًا، وكل جلسة 1 رصيد. راجع فتح جلسة.
كم يكلف؟
| ما تشغّله | الأرصدة |
|---|---|
| متصفح يعمل حتى 12 دقيقة | 1 |
| متصفح يعمل ساعة كاملة | 5 |
| هوية دائمة، كل 30 يومًا | 50 |
| جلسة على هوية دائمة (حتى ساعة واحدة) | 1 |
| متصفح يفشل في البدء | مُسترَد |
الرصيد الواحد يساوي $0.10 في باقة Starter بقيمة $20، وأقل في الباقات الأكبر. الرصيد لا تنتهي صلاحيته. الأسعار كاملة.
استكشاف الأخطاء وإصلاحها
401 Unauthorized عند الاتصال
لم تصل ترويسة X-API-Key إلى Browsa، أو المفتاح خاطئ. أرسلها في استدعاء الاتصال تمامًا كما في الأمثلة، وتأكد أن المفتاح يبدأ بـ agt_.
402 عند تشغيل متصفح
INSUFFICIENT_CREDIT يعني أن الرصيد لا يغطي مدة TTL التي طلبتها؛ وBUDGET_REACHED يعني أنك بلغت حد الإنفاق الشهري. راجع GET /v1/credits وGET /v1/budget.
ينقطع الاتصال بعد بضع دقائق
وصل المتصفح إلى نهاية مدة TTL. اطلب مدة أطول، حتى "1h".
أسئلة
لماذا لا يغيّر set_viewport_size() المتصفح؟
تُضبط أبعاد شاشة متصفح Browsa ووكيل المستخدم والمنطقة الزمنية واللغة والموقع الجغرافي معًا عند إنشائه، فترى الصفحة جهازًا واحدًا متسقًا. أوامر محاكاة CDP التي تغيّر أحدها وحده تُرجع نجاحًا ولا تغيّر شيئًا. اضبط screen_resolution وos_type عند إنشاء المتصفح، أو أضف cdp_overrides=allow إلى عنوان CDP إن أردت التحكم في المحاكاة بنفسك.
كيف أنزّل ملفًا من متصفح سحابي؟
الملفات التي تنزّلها الصفحة تبقى في المتصفح السحابي، ويُبلغ Playwright بأن التنزيل أُلغي. اجلب الملف من داخل الصفحة عبر page.evaluate()، الذي يستخدم ملفات تعريف الارتباط وعنوان IP الخاصين بالمتصفح، وأعِد البايتات بترميز base64.
كم متصفحًا يمكن تشغيله في وقت واحد؟
لكل مساحة عمل 6 خانات متصفح. كل متصفح قيد التشغيل يشغل خانة، وكذلك كل هوية محفوظة. طلب متصفح جديد مع امتلاء كل الخانات يُرجع 429 TOO_MANY_REQUESTS مع Retry-After: 30، ولا يُخصم شيء. راسل support@browsa.io إن احتجت المزيد.
هل توفر Browsa خوادم بروكسي؟
نعم. بروكسي مركز البيانات بـ 5 أرصدة لكل GB، والسكني بـ 50 رصيدًا لكل GB. أو مرّر بروكسي HTTP أو HTTPS أو SOCKS5 الخاص بك لكل متصفح، مجانًا. ومن دون بروكسي يستخدم المتصفح عنوان IP لمركز بيانات Browsa.