استدعاء solvethree من واجهة خلفية تستخدم ASP.NET Core

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

ضع مفتاح مساحة العمل في إعدادات الخادم باسم SOLVETHREE_API_KEY. أضف صنف العميل، ثم أزِل التعليق عن كود التسجيل المعروض تحت Program.cs وضعه قبل builder.Build().

// CaptchaClient.cs; .NET 8+, System.Net.Http.Json and System.Text.Json.Nodes.
using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text.Json.Nodes;

public sealed class CaptchaClient(HttpClient http)
{
    public async Task<JsonObject> CreateAsync(string site, string proxy, string requestId,
        CancellationToken cancellationToken)
    {
        using var response = await http.PostAsJsonAsync("tasks?waitMs=0",
            new { site, action = "login", proxy, requestId }, cancellationToken);
        response.EnsureSuccessStatusCode();
        return (await response.Content.ReadFromJsonAsync<JsonObject>(cancellationToken))!;
    }
    public async Task<JsonObject> GetAsync(string id, CancellationToken cancellationToken)
    {
        using var response = await http.GetAsync("tasks/" + Uri.EscapeDataString(id) + "?waitMs=15000",
            cancellationToken);
        response.EnsureSuccessStatusCode();
        return (await response.Content.ReadFromJsonAsync<JsonObject>(cancellationToken))!;
    }
}
// Program.cs, before builder.Build(), in an existing authenticated ASP.NET app:
// builder.Services.AddHttpClient<CaptchaClient>(http => {
//     http.BaseAddress = new Uri("https://api.solvethree.com/v1/");
//     http.Timeout = TimeSpan.FromSeconds(25);
//     http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(
//         "Bearer", builder.Configuration["SOLVETHREE_API_KEY"]
//             ?? throw new InvalidOperationException("Missing API key"));
// }).ConfigurePrimaryHttpMessageHandler(() => new HttpClientHandler {
//     AllowAutoRedirect = false
// });
// Inject CaptchaClient into your authenticated controller/service. Pass its
// cancellation token, create once, save id and poll GetAsync with a finite deadline.

يضبط التسجيل عنوان API الأساسي، ومصادقة Bearer، ومهلة نقل قدرها 25 ثانية، ويعطّل عمليات إعادة التوجيه التلقائية. احتفظ بالشرطة المائلة الختامية في العنوان الأساسي: يجب أن تُحلّ مسارات tasks النسبية للعميل ضمن /v1/.

يستخدم الكود المساعد امتدادات JSON الخاصة بـ HttpClient ويعيد JsonObject. تتحقّق كلتا الدالتين من نجاح HTTP قبل إلغاء التسلسل. احقن CaptchaClient في وحدة تحكم أو خدمة محمية بالمصادقة؛ فالكود المساعد نفسه لا يصادق الجهات المستدعية لتطبيقك ولا يتحقّق من صلاحياتها.

1. 1.

   اختر الموقع والإجراء والوكيل

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

2. 2.

   احفظ requestId قبل استدعاء CreateAsync

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

3. 3.

   استدعِ CreateAsync واحفظ معرّف المهمة المُعاد

   يرسل CreateAsync طلب POST واحدًا مع waitMs=0. مرّر CancellationToken الخاص بالجهة المستدعية. بمجرد حصولك على معرّف المهمة، استخدم GetAsync لاسترجاع تلك المهمة بدلًا من إنشاء أخرى.

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

يرمّز GetAsync معرّف المهمة المعروف للاستخدام الآمن في عنوان URL ويطلب waitMs=15000. تحدّ مهلة HttpClient البالغة 25 ثانية من مدة كل طلب HTTP؛ ولا تحدّ من إجمالي الوقت الذي يقضيه تطبيقك في الاستطلاع. اضبط مهلة نهائية إجمالية منفصلة ومرّر الإلغاء عبر كل استدعاء.

• pending أو solving: واصل فقط ما دامت مهلة الاستطلاع وإلغاء الجهة المستدعية يسمحان بذلك.
• ready: توقّف عن الاستطلاع واقرأ الحل. هذه هي الحالة الوحيدة التي تتضمن حلًا قابلًا للاستخدام.
• failed: توقّف عن الاستقصاء وافحص errorCode وerror.

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

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

تنتهي مهلة CreateAsync أو يُلغى قبل أن تتلقى معرّفًا.

قد يكون الخادم قد أنشأ المهمة بالفعل. لا يُلغي الإلغاء المحلي العمل عن بُعد.

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

تنتهي مهلة GetAsync أو تنقضي مهلة الاستطلاع النهائية.

لديك معرّف مهمة بالفعل، لذا لا يستلزم غياب الاستجابة إنشاء مهمة بديلة.

جرّب هذا: احتفظ بالمعرّف واسترجع تلك المهمة لاحقًا ضمن عملية جديدة محدودة المدة.

يعيد استدعاء HTTP استجابة غير ناجحة.

يطرح EnsureSuccessStatusCode استثناءً قبل أن يقرأ الكود المساعد محتوى استجابة ناجحة. يختلف هذا عن تلقي مهمة حالتها failed.

جرّب هذا: عالِج خطأ HTTP على حدة. صحّح المدخلات غير الصالحة بدلًا من إعادة المحاولة بها دون تغيير.

تصل المهمة إلى الحالة failed.

اقرأ errorCode وerror لمعرفة سبب فشل المهمة، مثل site-unreachable.

جرّب هذا: توقّف عن استطلاع حالة تلك المهمة وعالِج السبب المُبلّغ عنه قبل بدء عملية حل أخرى.

استخدم دليل أخطاء API عندما تحتاج إلى التمييز بين طلب API مرفوض وفشل نهائي في الحل.