استخدام أداة حل CAPTCHA في Express

استخدم Node.js 22 أو أحدث وExpress 5. ثبّت SDK الرسمية لـ JavaScript باستخدام التثبيت من أرشيف tarball الموضّح في الوثائق، بدلاً من افتراض نشرها في سجل npm. ينشئ المثال عميلاً واحداً من Solvethree خارج المعالجات.

• SOLVETHREE_API_KEY: مفتاح API لمساحة عملك. احتفظ به على الخادم.
• INTEGRATION_KEY: سر منفصل للجهات المستدعية الداخلية الموثوقة. يشترط المثال إرساله في ترويسة x-integration-key؛ لا توزّعه على عملاء المتصفح. إذا كانت لديك برمجيات وسيطة للمصادقة بالفعل، فاستخدمها بدلاً من الحماية بالمفتاح المشترك في المثال.
• CAPTCHA_SITE: اسم مضيف الوجهة، وليس عنوان URL كاملاً. اضبط ملف تعريف موقع نشطاً لمساحة عملك قبل إنشاء المهام؛ فإرسال اسم مضيف لا ينشئ ملف تعريف.
• SOLVETHREE_PROXY: الوكيل لهذه الوجهة. يوفّر المثال وكيلاً واحداً ويثبّت الإجراء على login. غيّر هذا الإجراء على الخادم إذا كانت وجهتك تستخدم إجراءً مختلفاً.

يستخدم هذا الطلب إعداد reCAPTCHA Enterprise الافتراضي. ويحتاج إلى site وaction ووكيل، وليس type أو url. راجع إعداد ملف تعريف الموقع إذا لم تكن الوجهة مضبوطة بعد.

// npm install express and the official solvethree SDK tarball.
import express from 'express';
import { Solvethree, SolvethreeError } from '@solvethree/sdk';
const app = express();
const client = new Solvethree({ apiKey: process.env.SOLVETHREE_API_KEY });
const secret = process.env.INTEGRATION_KEY;
if (!secret) throw new Error('Set INTEGRATION_KEY');
app.use((request, response, next) => {
  if (request.get('x-integration-key') !== secret) return response.sendStatus(401);
  next();
});
app.post('/captcha/tasks', async (request, response) => {
  const task = await client.createTask({
    site: process.env.CAPTCHA_SITE, action: 'login', proxy: process.env.SOLVETHREE_PROXY,
    requestId: request.get('x-request-id'),
  }, { waitMs: 0, signal: AbortSignal.timeout(20000) });
  response.json(task);
});
app.get('/captcha/tasks/:id', async (request, response) => {
  response.json(await client.getTask(request.params.id, { waitMs: 15000, signal: AbortSignal.timeout(25000) }));
});
app.use((error, request, response, next) => {
  if (error instanceof SolvethreeError) return response.status(502).json({ requestId: error.requestId, taskId: error.taskId });
  response.status(400).json({ error: 'Invalid task input or ID' });
});
app.listen(3000);

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

1. 1.

   عيّن معرّف طلب قبل الإنشاء

   أرسل x-request-id بقيمة تتكوّن من 1–64 حرفاً أو رقماً من ASCII أو شرطة سفلية أو واصلة. احتفظ به مع الطلب المنطقي لتتمكن من استعادة نتيجة الإنشاء إذا انتهت مهلة الاتصال.

2. 2.

   أرسل POST إلى /captcha/tasks مرة واحدة

   يستدعي المعالج createTask مع waitMs: 0 ويعيد المهمة. احتفظ بمعرّفها. تعني الاستجابة الناجحة أن لديك مهمة، وليس بالضرورة حلاً.

3. 3.

   استرجع الحالة باستخدام GET

   استدعِ /captcha/tasks/:id. واصل الاسترجاع ما دامت الحالة pending أو solving؛ ولا تكرّر POST للتحقق من التقدم. توقّف عند ready أو failed.

4. 4.

   استخدم حلاً جاهزاً فقط

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

لاستدعاء SDK الخاص بـ POST مهلة AbortSignal قدرها 20 ثانية. يتيح GET انتظار المهمة لمدة 15 ثانية ضمن مهلة استدعاء SDK قدرها 25 ثانية. قد تظل استجابة GET غير نهائية؛ افحص حالتها بدلاً من اعتبار انتهاء الانتظار فشلاً في الحل.

انتهاء مهلة الإنشاء لا يثبت أن solvethree رفض الطلب. إذا تلقيت معرّف مهمة، فاسترجعها. وإلا، فكرّر الإنشاء باستخدام معرّف الطلب نفسه ومدخلات المهمة دون تغيير لاستعادة المهمة الحالية. تؤدي إعادة استخدام هذا المعرّف مع مدخلات مختلفة إلى تعارض. ومن دون الاحتفاظ بمعرّف الطلب، قد يؤدي POST جديد إلى إنشاء عمل منفصل.

يمرّر Express 5 حالات الرفض في المعالجات غير المتزامنة إلى البرمجيات الوسيطة لمعالجة الأخطاء. يعيد المثال HTTP 502 عند SolvethreeError، ولا يكشف إلا معرّفَي الطلب والمهمة، دون الخطأ الخام أو بيانات الاعتماد أو الحل. أما استجابة HTTP 400 الاحتياطية فهي عامة؛ ولا تصنّف بدقة كل خطأ غير صادر عن SDK، بما في ذلك أخطاء انتهاء المهلة.

عالج أخطاء HTTP قبل قراءة حمولة النجاح. وبشكل منفصل، قد تكون حالة المهمة المسترجعة failed: افحص errorCode وerror، ثم أوقف الاستقصاء. تُردّ تكلفة عمليات الحل الفاشلة، لكن إعادة المحاولة بمدخلات غير صالحة دون تغيير لن تصلحها. استخدم مرجع أخطاء API لتشخيص الفشل المُبلَّغ عنه.