كيفية استخدام واجهة برمجة تطبيقات السحابة للمتصفح

سيأخذك هذا البرنامج التعليمي في رحلة عبر كل ما تحتاج لمعرفته لتسخير قوة أتمتة المتصفح المدفوعة بالذكاء الاصطناعي. سواء كنت تتطلع إلى أتمتة استخلاص البيانات، أو اختبار تطبيقات الويب الخاصة بك، أو إنشاء أدوات مراقبة متطورة، سيوفر لك هذا الدليل المعرفة والأمثلة اللازمة للبدء.

ما هو Browser Use Cloud؟

Browser Use Cloud هو منصة قوية تتيح لك إنشاء وإدارة وكلاء أتمتة المتصفح الذكية برمجياً. فكر في الأمر كامتلاك أسطول من المساعدين الافتراضيين الذين يمكنهم تصفح الويب، والتفاعل مع مواقع الويب، وأداء مهام معقدة نيابة عنك.

في جوهر المنصة يكمن مفهوم "المهمة" (task). المهمة هي مجموعة من التعليمات التي تقدمها لوكيل بلغة طبيعية. على سبيل المثال، يمكنك إعطاء وكيل مهمة مثل: "اذهب إلى hacker-news.com، ابحث عن أفضل 5 مقالات، واحفظ عناوينها وعناوين URL الخاصة بها في ملف." سيستخدم الوكيل بعد ذلك نموذج لغة كبير (LLM) لفهم وتنفيذ هذه التعليمات في بيئة متصفح حقيقية.

إحدى الميزات الأكثر إثارة في Browser Use Cloud هي حلقة التغذية الراجعة في الوقت الفعلي. كل مهمة تنشئها تأتي مع live_url. يوفر هذا العنوان URL معاينة حية وتفاعلية لما يفعله الوكيل. يمكنك مشاهدة الوكيل وهو يتصفح في الوقت الفعلي وحتى التحكم فيه إذا لزم الأمر. هذا يجعل تصحيح الأخطاء والمراقبة بديهيين للغاية.

الحصول على مفتاح API الخاص بك

قبل أن تتمكن من البدء في إنشاء الوكلاء، ستحتاج إلى مفتاح API. يقوم مفتاح API بمصادقة طلباتك وربطها بحسابك.

<ملاحظة> للحصول على مفتاح API الخاص بك، ستحتاج إلى اشتراك نشط في Browser Use Cloud. يمكنك إدارة اشتراكك والحصول على مفتاح API الخاص بك من صفحة الفوترة: cloud.browser-use.com/billing. </ملاحظة>

بمجرد حصولك على مفتاح API الخاص بك، تأكد من الحفاظ على أمانه. تعامل معه ككلمة مرور، ولا تكشف عنه أبدًا في رمز جانب العميل أو تلتزم به في التحكم في الإصدار. من الأفضل تخزينه في متغير بيئة آمن.

export BROWSER_USE_API_KEY="your_api_key_here"

فهم نموذج التسعير

تتمتع واجهة برمجة تطبيقات Browser Use Cloud بنموذج تسعير بسيط يعتمد على الدفع حسب الاستخدام. يضمن هذا أنك تدفع فقط مقابل ما تستخدمه، مما يجعله فعالاً من حيث التكلفة للمشاريع الصغيرة والكبيرة على حد سواء. يتكون التسعير من جزأين رئيسيين:

1. تكلفة تهيئة المهمة: يتم فرض رسوم ثابتة قدرها 0.01 دولار لكل مهمة تبدأها. يغطي هذا تكلفة إعداد بيئة المتصفح لوكيلك.
2. تكلفة خطوة المهمة: هذه هي التكلفة لكل إجراء أو "خطوة" يتخذها الوكيل. تعتمد التكلفة لكل خطوة على نموذج اللغة الكبير (LLM) الذي تختاره لتشغيل وكيلك.

تسعير خطوة LLM

تتمتع نماذج اللغة الكبيرة المختلفة بقدرات ونقاط سعر مختلفة. يمكنك اختيار النموذج الذي يناسب احتياجاتك من حيث الأداء والتكلفة. فيما يلي تفصيل للتكلفة لكل خطوة لكل نموذج متاح:

مثال على حساب التكلفة

لنتخيل أنك تريد أتمتة مهمة تتضمن تسجيل الدخول إلى موقع ويب، والانتقال إلى صفحة معينة، واستخلاص بعض البيانات. تقدر أن هذا سيستغرق حوالي 15 خطوة. إذا اخترت استخدام نموذج GPT-4o القوي، فسيتم حساب التكلفة الإجمالية على النحو التالي:

• تهيئة المهمة: 0.01 دولار
• خطوات المهمة: 15 خطوة × 0.03 دولار/خطوة = 0.45 دولار
• التكلفة الإجمالية: 0.01 دولار + 0.45 دولار = 0.46 دولار

يسمح لك هذا التسعير الشفاف بتوقع والتحكم في تكاليفك بفعالية.

إنشاء أول وكيل لك: مثال "مرحباً بالعالم!"

الآن للجزء المثير! لننشئ أول وكيل لأتمتة المتصفح. سنبدأ بمهمة بسيطة جدًا: الذهاب إلى Google والبحث عن "Browser Use".

سنستخدم curl لإجراء طلب POST إلى نقطة النهاية /api/v1/run-task. هذه هي نقطة النهاية الأساسية لإنشاء مهام جديدة.

curl -X POST <https://api.browser-use.com/api/v1/run-task> \\\\
  -H "Authorization: Bearer $BROWSER_USE_API_KEY" \\\\
  -H "Content-Type: application/json" \\\\
  -d '{
    "task": "Go to google.com and search for Browser Use"
  }'

دعنا نحلل هذا الأمر:

• curl -X POST ...: نحن نرسل طلب HTTP POST إلى عنوان URL المحدد.
• H "Authorization: Bearer $BROWSER_USE_API_KEY": هذا هو رأس المصادقة. يتضمن مفتاح API الخاص بك. نحن نستخدم متغير البيئة الذي قمنا بتعيينه سابقًا.
• H "Content-Type: application/json": يخبر هذا الرأس واجهة برمجة التطبيقات أننا نرسل البيانات بتنسيق JSON.
• d '{ "task": "..." }': هذا هو نص طلبنا. يحتوي حقل task على تعليمات اللغة الطبيعية لوكيلنا.

فهم استجابة API

عند إرسال هذا الطلب، ستستجيب واجهة برمجة التطبيقات بكائن JSON يحتوي على معلومات حول المهمة التي تم إنشاؤها حديثًا. إليك مثال على شكل الاستجابة:

{
  "task_id": "ts_2a9b4e7c-1d0f-4g8h-9i1j-k2l3m4n5o6p7",
  "status": "running",
  "live_url": "<https://previews.browser-use.com/ts_2a9b4e7c-1d0f-4g8h-9i1j-k2l3m4n5o6p7>"
}

• task_id: هذا هو معرف فريد لمهمتك. ستستخدم هذا المعرف لإدارة المهمة لاحقًا (مثل إيقافها مؤقتًا أو استئنافها أو إيقافها).
• status: يشير هذا إلى الحالة الحالية للمهمة. سيكون running (قيد التشغيل) في البداية.
• live_url: هذا هو عنوان URL للمعاينة المباشرة. انسخ والصق عنوان URL هذا في متصفحك لرؤية وكيلك وهو يعمل!

معاينات مباشرة تفاعلية

يعد live_url أحد أقوى ميزات Browser Use Cloud. إنه ليس مجرد بث فيديو للقراءة فقط؛ إنها جلسة تفاعلية بالكامل.

يمكنك تضمين live_url مباشرة في تطبيقاتك الخاصة باستخدام iframe. يتيح لك هذا بناء لوحات تحكم مخصصة وأدوات مراقبة تتضمن عرضًا في الوقت الفعلي لوكلائك.

إليك مقتطف HTML بسيط لتضمين المعاينة المباشرة:

<!DOCTYPE html>
<html>
<head>
  <title>معاينة الوكيل المباشرة</title>
  <style>
    body, html { margin: 0; padding: 0; height: 100%; overflow: hidden; }
    iframe { width: 100%; height: 100%; border: none; }
  </style>
</head>
<body>
  <iframe src="YOUR_LIVE_URL_HERE"></iframe>
</body>
</html>

استبدل YOUR_LIVE_URL_HERE بـ live_url من استجابة API. عند فتح ملف HTML هذا في متصفح، سترى شاشة الوكيل. يمكنك النقر والكتابة والتمرير كما لو كنت تتصفح على جهاز الكمبيوتر الخاص بك. هذا مفيد بشكل لا يصدق من أجل:

• تصحيح الأخطاء: إذا علق وكيل، يمكنك على الفور رؤية السبب وما يظهر على شاشته.
• التدخل اليدوي: إذا تطلبت مهمة خطوة يصعب أتمتتها (مثل حل CAPTCHA معقد)، يمكنك السيطرة، إكمال الخطوة يدويًا، ثم السماح للوكيل باستئناف عمله.
• العروض التوضيحية: إنها طريقة رائعة لإظهار أصحاب المصلحة ما تقوم به الأتمتة الخاصة بك.

إدارة دورة حياة المهمة

بمجرد تشغيل المهمة، لديك تحكم كامل في دورة حياتها. يمكنك إيقاف المهام مؤقتًا واستئنافها وإيقافها باستخدام API. ستحتاج إلى task_id لجميع عمليات الإدارة.

إيقاف المهمة مؤقتًا واستئنافها

هناك العديد من الأسباب التي قد تجعلك ترغب في إيقاف مهمة مؤقتًا. ربما تحتاج إلى فحص صفحة الويب يدويًا، أو ربما تريد الانتظار حتى يحدث حدث خارجي قبل المتابعة.

لإيقاف مهمة مؤقتًا، أرسل طلب POST إلى نقطة النهاية /api/v1/pause-task:

curl -X POST <https://api.browser-use.com/api/v1/pause-task> \\\\
  -H "Authorization: Bearer $BROWSER_USE_API_KEY" \\\\
  -H "Content-Type: application/json" \\\\
  -d '{
    "task_id": "YOUR_TASK_ID_HERE"
  }'

سينهي الوكيل خطوته الحالية ثم يدخل في حالة paused (متوقفة مؤقتًا).

لاستئناف المهمة، أرسل طلب POST إلى نقطة النهاية /api/v1/resume-task:

curl -X POST <https://api.browser-use.com/api/v1/resume-task> \\\\
  -H "Authorization: Bearer $BROWSER_USE_API_KEY" \\\\
  -H "Content-Type: application/json" \\\\
  -d '{
    "task_id": "YOUR_TASK_ID_HERE"
  }'

سيبدأ الوكيل من حيث توقف تمامًا.

إيقاف المهمة

إذا كنت ترغب في إنهاء مهمة بشكل دائم، يمكنك استخدام نقطة النهاية /api/v1/stop-task. هذا مفيد إذا كانت المهمة مكتملة، أو حدث خطأ، أو لم تعد هناك حاجة إليها.

curl -X POST <https://api.browser-use.com/api/v1/stop-task> \\\\
  -H "Authorization: Bearer $BROWSER_USE_API_KEY" \\\\
  -H "Content-Type: application/json" \\\\
  -d '{
    "task_id": "YOUR_TASK_ID_HERE"
  }'

<ملاحظة> بمجرد إيقاف المهمة، لا يمكن استئنافها. يتم تدمير بيئة المتصفح، ويتم تنظيف جميع الموارد المرتبطة بها. </ملاحظة>

إنشاء المهام المتقدم

مثال "مرحباً بالعالم!" كان مجرد البداية. تدعم نقطة النهاية run-task أكثر من مجرد سلسلة task بسيطة. يمكنك تخصيص سلوك وكيلك من خلال توفير معلمات إضافية.

اختيار LLM

كما رأينا في قسم التسعير، يمكنك الاختيار من بين عدة نماذج لغة كبيرة (LLMs) مختلفة لتشغيل وكيلك. يمكنك تحديد النموذج في طلب run-task باستخدام المعلمة model.

على سبيل المثال، لاستخدام نموذج Claude 3.7 Sonnet، ستقوم بإجراء الطلب التالي:

curl -X POST <https://api.browser-use.com/api/v1/run-task> \\\\
  -H "Authorization: Bearer $BROWSER_USE_API_KEY" \\\\
  -H "Content-Type: application/json" \\\\
  -d '{
    "task": "Go to reddit.com/r/programming and find the top post of the day.",
    "model": "claude-3.7-sonnet-20250219"
  }'

إذا لم تحدد نموذجًا، فستستخدم واجهة برمجة التطبيقات نموذجًا افتراضيًا، وهو عادةً خيار فعال من حيث التكلفة والأداء مثل GPT-4o mini.

بناء العميل الخاص بك

بينما curl رائع للاختبارات البسيطة، من المرجح أن ترغب في دمج واجهة برمجة تطبيقات Browser Use Cloud في تطبيقاتك باستخدام مكتبة عميل مناسبة. أفضل طريقة للقيام بذلك هي استخدام مواصفات OpenAPI الخاصة بنا لإنشاء عميل آمن من حيث الأنواع (type-safe).

مواصفات OpenAPI هي طريقة موحدة لوصف واجهات برمجة تطبيقات REST. يمكنك العثور على مواصفاتنا هنا: http://api.browser-use.com/openapi.json.

إنشاء عميل Python

لمطوري Python، نوصي بـ openapi-python-client. يقوم بإنشاء عميل حديث، يعتمد على async أولاً، مع تلميحات أنواع كاملة.

أولاً، قم بتثبيت أداة الإنشاء:

# We recommend using pipx to keep your global environment clean
pipx install openapi-python-client --include-deps

الآن، قم بإنشاء العميل:

openapi-python-client generate --url <http://api.browser-use.com/openapi.json>

سيؤدي هذا إلى إنشاء دليل جديد يحتوي على حزمة عميل Python الخاصة بك. يمكنك تثبيتها باستخدام pip:

pip install .

الآن يمكنك استخدام العميل في كود Python الخاص بك:

import asyncio
from browser_use_api import Client
from browser_use_api.models import RunTaskRequest

async def main():
    client = Client(base_url="<https://api.browser-use.com/api/v1>")
    request = RunTaskRequest(task="Go to ycombinator.com and list the top 3 companies.")

    response = await client.run_task.api_v1_run_task_post(
        client=client,
        json_body=request,
        headers={"Authorization": f"Bearer {YOUR_API_KEY}"}
    )

    if response:
        print(f"Task created with ID: {response.task_id}")
        print(f"Live URL: {response.live_url}")

if __name__ == "__main__":
    asyncio.run(main())

إنشاء عميل TypeScript/JavaScript

لمشاريع الواجهة الأمامية أو Node.js، يعد openapi-typescript أداة ممتازة لإنشاء تعريفات أنواع TypeScript من مواصفات OpenAPI.

أولاً، قم بتثبيت المولد كاعتماد تطوير:

npm install -D openapi-typescript

ثم قم بتشغيل المولد:

npx openapi-typescript <http://api.browser-use.com/openapi.json> -o src/browser-use-api.ts

سيؤدي هذا إلى إنشاء ملف واحد، src/browser-use-api.ts، يحتوي على جميع تعريفات الأنواع لواجهة برمجة التطبيقات. يمكنك بعد ذلك استخدام هذه الأنواع مع عميل HTTP المفضل لديك، مثل fetch أو axios، لإجراء طلبات آمنة من حيث الأنواع.

إليك مثال باستخدام fetch في مشروع TypeScript:

import { paths } from './src/browser-use-api';

const API_URL = "<https://api.browser-use.com/api/v1>";

type RunTaskRequest = paths["/run-task"]["post"]["requestBody"]["content"]["application/json"];
type RunTaskResponse = paths["/run-task"]["post"]["responses"]["200"]["content"]["application/json"];

async function createTask(task: string, apiKey: string): Promise<RunTaskResponse> {
  const body: RunTaskRequest = { task };

  const response = await fetch(`${API_URL}/run-task`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${apiKey}`,
    },
    body: JSON.stringify(body),
  });

  if (!response.ok) {
    throw new Error(`API request failed with status ${response.status}`);
  }

  return response.json() as Promise<RunTaskResponse>;
}

async function run() {
  const apiKey = process.env.BROWSER_USE_API_KEY;
  if (!apiKey) {
    throw new Error("API key not found in environment variables.");
  }

  try {
    const result = await createTask("Find the current weather in New York City.", apiKey);
    console.log("Task created:", result);
  } catch (error) {
    console.error("Failed to create task:", error);
  }
}

run();