استدعاء CAPTCHA API من Laravel

1. 1.

   تفعيل ملف تعريف الموقع

   أعِدّ اسم المضيف المستهدف في لوحة التحكم ليكون لمساحة عملك ملف تعريف reCAPTCHA نشط. إرسال اسم مضيف ضمن مهمة لا ينشئ ملف تعريف. راجع إعداد ملف تعريف الموقع.

2. 2.

   إضافة إعدادات الخادم

   أضف إدخال solvethree الوارد في المثال إلى المصفوفة الموجودة في config/services.php. اضبط SOLVETHREE_API_KEY وCAPTCHA_SITE وSOLVETHREE_PROXY في بيئة الخادم. لا تضع هذه القيم في كود المتصفح؛ CAPTCHA_SITE هو اسم المضيف، وليس عنوان URL كاملًا.

3. 3.

   مطابقة الإجراء المستهدف

   يرسل المثال login. غيّره إلى الإجراء المستخدم في طلبك المستهدف. يوفّر المثال proxy واحدًا؛ فلا ترسل proxyCandidates أيضًا.

<?php
// app/Services/CaptchaApi.php — configure services.solvethree in config/services.php.
namespace App\Services;

use Illuminate\Support\Facades\Http;
use InvalidArgumentException;

final class CaptchaApi
{
    private function client()
    {
        return Http::baseUrl('https://api.solvethree.com/v1')
            ->withToken(config('services.solvethree.key'))
            ->acceptJson()->asJson()->connectTimeout(10)->timeout(25);
    }

    public function create(string $requestId): array
    {
        if (!preg_match('/^[A-Za-z0-9_-]{1,64}$/', $requestId)) {
            throw new InvalidArgumentException('Invalid logical request ID');
        }
        // The caller keeps this requestId; do not generate another on a timeout.
        return $this->client()->post('/tasks?waitMs=0', [
            'site' => config('services.solvethree.site'),
            'action' => 'login',
            'proxy' => config('services.solvethree.proxy'),
            'requestId' => $requestId,
        ])->throw()->json();
    }

    public function retrieve(string $taskId): array
    {
        if (!preg_match('/^[A-Za-z0-9_-]{1,128}$/', $taskId)) {
            throw new InvalidArgumentException('Invalid task ID');
        }
        return $this->client()->get('/tasks/'.rawurlencode($taskId), ['waitMs' => 15000])
            ->throw()->json();
    }
}
// config/services.php entry:
// 'solvethree' => ['key' => env('SOLVETHREE_API_KEY'),
//   'site' => env('CAPTCHA_SITE'), 'proxy' => env('SOLVETHREE_PROXY')],
// Invoke from your authenticated controller/job. Poll retrieve only while pending
// or solving; ready contains the solution, failed is terminal. Never use retry()
// on create without preserving both this ID and the exact original inputs.

ترسل withToken مفتاح مساحة العمل باستخدام مصادقة Bearer. جسم POST مسطح: الحقول site وaction وproxy وrequestId في المستوى الأعلى. لا تضف حقل type أو url لـ reCAPTCHA. يؤدي إغفال recaptchaType إلى اختيار القيمة الافتراضية الموثقة enterprise-v3.

تستدعي كلتا الطريقتين throw() قبل json(). لا يطرح عميل HTTP في Laravel استثناءً افتراضيًا عند استجابات HTTP غير الناجحة، لذا يمنع هذا المستدعي من التعامل مع حمولة خطأ HTTP على أنها استجابة مهمة ناجحة. تضبط الخدمة مهلتي الاتصال والطلب، وتتعمد عدم إعادة محاولة POST تلقائيًا.

1. 1.

   الإنشاء مرة واحدة لكل عملية حل منطقية

   من وحدة التحكم أو المهمة البرمجية التي تعمل ضمن سياق مصادَق عليه، احتفظ بقيمة requestId يولدها المستدعي قبل استدعاء create. يجب أن تحتوي على من 1 إلى 64 حرفًا أو رقمًا أو شرطة سفلية أو شرطة ضمن ASCII. احفظ معرّف المهمة المُعاد بشكل منفصل: معرّف الطلب المنطقي مخصص لاسترداد عملية الإنشاء؛ أما معرّف المهمة فهو ما تقبله retrieve.

2. 2.

   استرجاع المهمة الحالية

   استدعِ retrieve باستخدام معرّف المهمة المحفوظ. إذا كانت الحالة pending أو solving، فرتّب لاسترجاع لاحق بدلًا من تشغيل حلقة متلاحقة في وحدة التحكم. حدّد للمستدعي مهلة انتظار إجمالية؛ فمهلة HTTP الخاصة بالخدمة تحدّ من مدة كل طلب، لا من عمر عملية الحل. بلوغ تلك المهلة ليس سببًا لإنشاء مهمة أخرى.

3. 3.

   معالجة النتيجة النهائية

   في حالة failed، أوقف الاسترجاع وافحص errorCode وerror؛ تُرد تكلفة محاولات الحل الفاشلة. في حالة ready، استخدم رمز الحل المُعاد. أرسله باستخدام هوية userAgent وsecChUa المُعادة والخادم الوكيل نفسه المستخدم للحل. يظل الحل الجاهز بحاجة إلى قبول الجهة المستهدفة.

افصل أخطاء HTTP عن حالات فشل المهام. تتولى throw() معالجة استجابة HTTP غير الناجحة؛ أما الاستجابة الناجحة التي تحتوي على failed فتحتاج إلى معالجة على مستوى المهمة. لا تُعد المحاولة بمدخلات غير صالحة دون تغيير، ولا تفترض أن كل فشل يعني عدم كفاية الرصيد. راجع معالجة أخطاء API.

انتهاء مهلة الاتصال لا يخبرك بما إذا كانت solvethree قد أنشأت المهمة. إذا كان لديك معرّف المهمة بالفعل، فاسترجعها. وإلا، فكرر الإنشاء باستخدام requestId نفسه ومدخلات المهمة نفسها تمامًا لاسترداد المهمة الموجودة.