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

1. 1.

   أتِح الموقع لمساحة عملك

   اضبط ملفًا تعريفيًا نشطًا لاسم المضيف المستهدف في وحدة التحكم. إرسال اسم مضيف وإجراء لا يُنشئ ملفًا تعريفيًا. راجع إعداد الملف التعريفي للموقع إذا لم يُنجز ذلك بعد.

2. 2.

   وفّر متغيرات البيئة

   عيّن SOLVETHREE_API_KEY وSOLVETHREE_PROXY في بيئة عملية PowerShell باستخدام آليتك المعتادة للتعامل مع الأسرار. تحقّق من أن كليهما يحتوي على قيمة قبل التشغيل. يصبح مفتاح API جزءًا من ترويسة Bearer؛ ولا يوضع في JSON الخاص بالمهمة.

3. 3.

   استبدل اسم المضيف والإجراء في المثال

   غيّر accounts.example.com وlogin إلى اسم المضيف والإجراء المطلوبين لتكاملك. استخدم اسم مضيف، لا عنوان URL كاملًا. يستخدم الطلب Enterprise v3 افتراضيًا، لذا لا يحتاج إلى حقل type أو url.

#requires -Version 7.5
$ErrorActionPreference = 'Stop'
$apiBase = 'https://api.solvethree.com/v1'
$headers = @{ Authorization = "Bearer $env:SOLVETHREE_API_KEY"; Accept = 'application/json' }
$taskInput = @{ site = 'accounts.example.com'; action = 'login'; proxy = $env:SOLVETHREE_PROXY; requestId = [guid]::NewGuid().ToString() }
$requestClock = [Diagnostics.Stopwatch]::StartNew()
function Call-TaskApi($Method, $Path, $Payload = $null) {
    $remaining = 180 - $requestClock.Elapsed.TotalSeconds
    if ($remaining -le 0) { throw 'Local deadline reached' }
    $seconds = [int][Math]::Ceiling([Math]::Min(25, $remaining))
    $options = @{ Method = $Method; Uri = "$apiBase$Path"; Headers = $headers;
        ConnectionTimeoutSeconds = $seconds; OperationTimeoutSeconds = $seconds;
        MaximumRetryCount = 0; MaximumRedirection = 0 }
    if ($null -ne $Payload) { $options.Body = $Payload | ConvertTo-Json -Depth 6; $options.ContentType = 'application/json' }
    Invoke-RestMethod @options
}
$taskId = $null
try {
    $result = Call-TaskApi 'POST' '/tasks?waitMs=0' $taskInput
    $taskId = $result.id
    while ($result.status -in @('pending', 'solving')) {
        $escapedId = [uri]::EscapeDataString($taskId)
        $result = Call-TaskApi 'GET' "/tasks/$escapedId`?waitMs=15000"
        if ($result.status -in @('pending', 'solving')) { Start-Sleep -Seconds 1 }
    }
    if ($result.status -ne 'ready') { throw "Task failed: $($result.errorCode)" }
    Write-Host "Ready task: $taskId"
    # Submit $result.solution.token with userAgent/secChUa and the original proxy.
} catch {
    Write-Host "Recovery requestId=$($taskInput.requestId) taskId=$taskId"
    throw
}

يرسل البرنامج النصي طلب POST واحدًا إلى /v1/tasks?waitMs=0. وتكون الطلبات اللاحقة طلبات GET للمعرّف المُعاد، باستخدام waitMs=15000. تُبقي الحالتان pending وsolving الحلقة قيد التشغيل؛ وتنهيها أي حالة أخرى.

يحوّل ConvertTo-Json جدول التجزئة الخاص بالمهمة إلى JSON بدلًا من الاعتماد على JSON بعلامات اقتباس مكتوبة يدويًا أو على أمر صدفة. ويُرمّز معرّف المهمة لعنوان URL قبل الاستطلاع. احتفظ بهذه الأجزاء عند تكييف المثال.

يتحقّق Stopwatch من ميزانية زمنية محلية قدرها 180 ثانية قبل كل استدعاء API. تُحدَّد لكل استدعاء مهلتا اتصال وتنفيذ لا تتجاوزان 25 ثانية، وتُخفَّضان مع تناقص الوقت المتبقي. بعد استطلاع يُعيد حالة غير نهائية، يتوقف البرنامج النصي مؤقتًا لمدة ثانية واحدة. تمنع الميزانية الاستطلاع بلا نهاية؛ لكنها لا تضمن توقفًا عند وقت فعلي دقيق.

يعطّل MaximumRetryCount = 0 إعادة محاولات HTTP التلقائية، ويرفض MaximumRedirection = 0 عمليات إعادة التوجيه. تتطلب معاملات المهلة المستخدمة هنا PowerShell 7.5+، وليس أي تثبيت من PowerShell 7. توثّق Microsoft هذه المعاملات في مرجع Invoke-RestMethod.

عند الحالة ready، تكون قيمة reCAPTCHA المطلوب إرسالها هي $result.solution.token. أما $taskId فيحدّد مهمة solvethree فقط. يتوقف المثال قبل إرسال طلب التطبيق إلى هدفك.

أرسل الرمز مع userAgent وsecChUa من الحل المُعاد، باستخدام الوكيل الأصلي. لا تستبدلهما بهوية متصفح غير ذات صلة، ولا ترسله إلى هدف مختلف. تعني ready أن solvethree أنشأ حلًا؛ ولا تثبت أن الهدف قبل طلب تطبيقك.

يطرح Invoke-RestMethod استثناء HTTP أو اتصال

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

جرّب هذا: افحص حالة HTTP وتفاصيل الاستجابة عند توفرها. صحّح المدخلات غير الصالحة بدلًا من إعادة المحاولة دون تغييرها. إذا كانت نتيجة إنشاء المهمة غير مؤكدة، فاستردّها كما هو موضّح أدناه.

تعيد المهمة الحالة failed

افحص كلًا من $result.errorCode و$result.error. يتضمن الاستثناء الذي يطرحه البرنامج النصي عند انتهاء المهمة رمز الخطأ فقط.

جرّب هذا: توقف عن استطلاع تلك المهمة وعالج السبب المُبلّغ عنه. مثلًا، يُعدّ site-unreachable خطأً في المهمة، وليس دليلًا على فشل طلب API نفسه. راجع أخطاء CAPTCHA API.

انتهاء المهلة لا يثبت فشل طلب الإنشاء. تطبع كتلة catch قيمة requestId وقيمة taskId إذا تم استلامها. احتفظ بهذه القيم.

1. 1.

   إذا كان لديك معرّف مهمة، فاسترجع تلك المهمة

   تابع باستخدام GET /v1/tasks/:id بدلًا من إنشاء مهمة أخرى. بلوغ الموعد النهائي المحلي للبرنامج النصي لا يثبت فشل المهمة البعيدة.

2. 2.

   إذا لم يُعِد الإنشاء معرّف مهمة، فأعِد استخدام الطلب الأصلي

   أعِد إرسال مدخلات المهمة نفسها مع requestId نفسه لاسترداد المهمة الموجودة. يؤدي تغيير المدخلات مع إعادة استخدام ذلك المعرّف إلى تعارض.

3. 3.

   لا تُعِد تشغيل هذا البرنامج النصي كإجراء للاسترداد

   يولّد التشغيل الجديد GUID جديدًا، وبالتالي طلبًا منطقيًا جديدًا. للاستخدام دون إشراف، احفظ requestId الأصلي ومدخلات المهمة بأمان قبل POST، ثم احفظ معرّف المهمة عند وصوله. يطبع المثال معرّفات الاسترداد عند الفشل، لكنه لا يحفظها بصورة دائمة لتبقى متاحة بعد فقدان العملية.

أبقِ المدخلات المحفوظة خارج السجلات العادية إذا كان عنوان URL للوكيل يحتوي على بيانات اعتماد. تحتاج إلى المدخلات الأصلية للاسترداد، لا إلى نسخة أخرى من مفتاح API.