استخدام حزمة SDK لـ Node.js في AWS Lambda

1. 1.

   ثبّت الاعتمادية

   هيّئ حزمة npm في دليل بناء نظيف. استخدم npm لتثبيت أرشيف tar الرسمي من https://solvethree.com/downloads/solvethree-sdk-0.1.0.tgz. فهو يوفر الاستيراد @solvethree/sdk؛ لا تفترض وجود إصدار في سجل npm.

2. 2.

   اضبط مساحة العمل والهدف

   اضبط متغيرات بيئة خاصة في Lambda بأسماء SOLVETHREE_API_KEY وCAPTCHA_SITE وSOLVETHREE_PROXY. استخدم مفتاح API لمساحة العمل، واسم المضيف المستهدف بدلًا من عنوان URL كامل، والوكيل الخاص بهذه المهمة. يجب أن تحتوي مساحة العمل مسبقًا على ملف تعريف نشط لذلك الموقع؛ راجع إعداد ملف تعريف الموقع.

3. 3.

   احفظ دالة المعالجة وجهّز حزمتها

   احفظ المثال أدناه باسم index.mjs. أنشئ ملف ZIP يحتوي على index.mjs وبيانات الحزمة الوصفية ودليل node_modules المثبّت في جذر الأرشيف، وليس داخل دليل مشروع حاوٍ. لا تضع بيانات الاعتماد في ملف ZIP.

4. 4.

   انشر عبر عملية Lambda المعتمدة لديك

   استخدم بيئة تشغيل Node.js 22 واضبط دالة المعالجة على index.handler. استدعها عبر خادمك الخلفي المصرّح له أو تدفق IAM، مع توفير requestId ثابت للعملية المنطقية. حافظ على خصوصية بيانات الحل المُعادة.

يستخدم المثال الإجراء login؛ غيّره إلى الإجراء الذي يتوقعه هدفك قبل النشر. يرسل proxy واحدًا ويستخدم نوع الطلب الافتراضي enterprise-v3. لا تضف حقلي reCAPTCHA‏ type أو url.

import { Solvethree, SolvethreeError, TaskFailedError, ApiError } from '@solvethree/sdk';
const client = new Solvethree({ apiKey: process.env.SOLVETHREE_API_KEY });
export const handler = async (event, context) => {
  const timeoutMs = Math.min(180000, context.getRemainingTimeInMillis() - 1500);
  if (timeoutMs < 1000) throw new Error('Not enough execution time to start a task');
  // The caller supplies one stable ID for this logical job; Lambda retries must
  // reuse it. awsRequestId changes with invocations and is not that logical ID.
  if (!event.requestId) throw new Error('Provide a stable requestId');
  try {
    return await client.solve({
      site: process.env.CAPTCHA_SITE, action: 'login', proxy: process.env.SOLVETHREE_PROXY,
      requestId: event.requestId,
    }, { timeoutMs, signal: AbortSignal.timeout(timeoutMs) });
  } catch (error) {
    if (error instanceof TaskFailedError) return { status: 'failed', id: error.taskId, errorCode: error.errorCode };
    if (error instanceof ApiError) return { apiError: error.status, requestId: error.requestId };
    if (error instanceof SolvethreeError) return { interrupted: true, requestId: error.requestId, taskId: error.taskId };
    throw error;
  }
};
// Invoke through your authorized backend/IAM flow. The return value is private
// solution data; do not attach this handler to an unauthenticated public URL.

تقرأ دالة المعالجة وقت التنفيذ المتبقي في Lambda، وتحتفظ بـ 1,500 مللي ثانية، وتضع حدًا أقصى لانتظار SDK يبلغ 180,000 مللي ثانية. يخص هذا الحد هذا المثال؛ وليس حدًا عامًا لتنفيذ Lambda. إذا تبقى أقل من ثانية واحدة بعد الوقت المحجوز، ترفض دالة المعالجة البدء.

تستخدم مهلة SDK وإشارة الإلغاء كلتاهما الموعد النهائي المحسوب. تنشئ solve المهمة مرة واحدة وتستطلع حالتها حتى تصبح جاهزة أو يحدث خطأ. يتيح الوقت المحجوز لمعالجة الأخطاء إعادة معلومات الاستعادة، لكن إنهاء Lambda قسرًا قد يظل يمنع أي استجابة.

يجب على المستدعي الاحتفاظ بـ event.requestId عبر محاولات إعادة الاستدعاء. استخدم 1–64 حرفًا من حروف ASCII أو أرقامًا أو شرطات سفلية أو شرطات. لا تستخدم awsRequestId: فهو يحدد استدعاءً، وليس طلب الحل المنطقي.

يُعاد طرح أخطاء التحقق والأخطاء غير المتوقعة. لا تحوّل دالة المعالجة كل استثناء إلى استجابة انقطاع.

1. 1.

   استعد باستخدام معرّف المهمة عند توفره

   استرجع المهمة الموجودة باستخدام getTask. تعني pending وsolving أنها لا تزال قيد التنفيذ؛ وحدها ready تتضمن حلًا قابلًا للاستخدام. أبقِ أي انتظار إضافي ضمن الميزانية الزمنية المتبقية للاستدعاء الجديد.

2. 2.

   وإلا، فاستعد باستخدام معرّف الطلب المنطقي

   أعد إرسال طلب المهمة نفسه باستخدام requestId الأصلي للجهة المستدعية. تُعيد المدخلات المتطابقة المهمة الحالية؛ أما المدخلات المختلفة فتؤدي إلى تعارض. أبقِ الموقع والإجراء والوكيل دون تغيير أثناء الاسترداد، حتى عند تغيير الإعدادات.

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

تُعيد SDK بيانات الحل؛ ولا تطبّقها على الهدف. عندما يرسلها تطبيقك، استخدم الوكيل المُعدّ والقيمتين المُعادتين userAgent وsecChUa. لا تستبدلهما بهوية متصفح أو عنوان URL مستهدف لا صلة لهما بالمهمة. تعني المهمة الجاهزة أنه تم إنشاء حل، لا أن الهدف قَبِل الطلب اللاحق.