استخدام SDK الخاص بـ Go في خادم net/http

1. 1.

   ثبّت Go SDK

   استخدم Go 1.22 أو أحدث. داخل وحدة Go مهيّأة، ثبّت SDK الرسمية باستخدام go get solvethree.com/[email protected]. احفظ المثال أدناه باسم main.go.

2. 2.

   ضبط بيئة الخادم

   اضبط SOLVETHREE_API_KEY على مفتاح API لمساحة عملك، وINTEGRATION_KEY على سر منفصل لمستدعي هذا الخادم الداخلي. اضبط CAPTCHA_SITE على اسم المضيف المستهدف، وSOLVETHREE_PROXY على عنوان URL لبروكسي HTTP أو HTTPS المستخدم للحل. احتفظ بكلا المفتاحين على خوادم موثوقة.

3. 3.

   جهّز الهدف المضبوط

   تأكد من أن للموقع ملف تعريف نشطًا متاحًا لمساحة عملك؛ راجع إعداد ملف تعريف الموقع. يثبّت المثال الإجراء على login. غيّره إلى الإجراء الذي يتوقعه هدفك قبل تشغيل الخادم. توفير اسم مضيف وإجراء لا ينشئ ملف تعريف.

package main

import (
    "context"
    "encoding/json"
    "errors"
    "log"
    "net/http"
    "os"
    "time"
    solvethree "solvethree.com/sdk"
)

func main() {
    client, err := solvethree.NewClient(os.Getenv("SOLVETHREE_API_KEY"), nil)
    if err != nil { log.Fatal(err) }
    secret := os.Getenv("INTEGRATION_KEY")
    if secret == "" { log.Fatal("Set INTEGRATION_KEY") }
    authorize := func(w http.ResponseWriter, r *http.Request) bool {
        if r.Header.Get("X-Integration-Key") != secret { http.Error(w, "Unauthorized", 401); return false }
        return true
    }
    respond := func(w http.ResponseWriter, result *solvethree.TaskResult, err error) {
        w.Header().Set("Content-Type", "application/json")
        if err != nil {
            var recovery *solvethree.Error
            w.WriteHeader(http.StatusBadGateway)
            ids := map[string]string{"error": "Solver request failed"}
            if errors.As(err, &recovery) { ids["requestId"] = recovery.RequestID; ids["taskId"] = recovery.TaskID }
            _ = json.NewEncoder(w).Encode(ids)
            return
        }
        _ = json.NewEncoder(w).Encode(result)
    }
    mux := http.NewServeMux()
    mux.HandleFunc("POST /captcha/tasks", func(w http.ResponseWriter, r *http.Request) {
        if !authorize(w,r) { return }
        input := solvethree.TaskRequest{Site: os.Getenv("CAPTCHA_SITE"), Action:"login",
            Proxy:os.Getenv("SOLVETHREE_PROXY"), RequestID:r.Header.Get("X-Request-ID")}
        if err := input.Validate(); err != nil { http.Error(w,"Invalid task input",400);return }
        ctx,cancel := context.WithTimeout(r.Context(),20*time.Second);defer cancel()
        zero:=0
        result,err:=client.CreateTask(ctx,input,&zero)
        respond(w,result,err)
    })
    mux.HandleFunc("GET /captcha/tasks/{id}", func(w http.ResponseWriter, r *http.Request) {
        if !authorize(w,r) { return }
        ctx,cancel:=context.WithTimeout(r.Context(),25*time.Second);defer cancel()
        result,err:=client.GetTask(ctx,r.PathValue("id"),15000)
        respond(w,result,err)
    })
    server:=&http.Server{Addr:"127.0.0.1:3000", Handler:mux, ReadHeaderTimeout:5*time.Second}
    log.Fatal(server.ListenAndServe())
}

شغّل الوحدة باستخدام go run .. يستمع الخادم على 127.0.0.1:3000. ويستخدم موجّه net/http القياسي في Go، لذلك لا يلزم إطار عمل. يُنشأ عميل SDK مرة واحدة وهو آمن للاستخدام المتزامن.

تستخدم المهمة وضع reCAPTCHA الافتراضي enterprise-v3. وتوفّر اسم مضيف الموقع وإجراءً وبروكسي واحدًا، وليس type أو url. لا يُستخدم جسم طلب POST، لذلك لا يمكن للمستدعين اختيار أهداف أو بروكسيات عشوائية.

أرسل POST /captcha/tasks مع الترويسة X-Integration-Key. وأرسل أيضًا X-Request-ID يُنشئه المستدعي حتى تتمكن من استعادة المهمة إذا انقطع الاتصال قبل استلام معرّفها. استخدم 1–64 حرفًا من حروف ASCII أو الأرقام أو الشرطات السفلية أو الشرطات.

يتحقق المعالج من صلاحية المهمة المضبوطة، ثم يستدعي CreateTask بقيمة انتظار صفرية. ويطلب إنشاء المهمة دون انتظار اكتمال الحل. يحد سياقه البالغ 20 ثانية من مدة انتظار طلب HTTP هذا؛ وليس مهلةً للحل.

عند النجاح، يعيد المعالج نتيجة المهمة من SDK. احفظ معرّف المهمة واستخدم مسار GET للتحققات اللاحقة. لا تعتبر نجاح POST دليلًا على توفر رمز قابل للاستخدام.

يتطلب كلا المسارين مفتاح التكامل. هذه واجهة داخلية موثوقة، وليست آلية تفويض لكل مستخدم: يتشارك المستدعون الذين يحملون هذا المفتاح الوصول عبر مساحة العمل المضبوطة.

أرسل GET /captcha/tasks/{id} مع ترويسة مفتاح التكامل نفسها. يستدعي المعالج GetTask فقط؛ ولا ينشئ أبدًا مهمة بديلة. ويطلب انتظارًا يصل إلى 15 ثانية ضمن سياق طلب مدته 25 ثانية.

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

تحقق من رمز حالة استجابة HTTP قبل فك ترميز نتيجة مهمة ناجحة. في هذا الخادم، تُعيد الطلبات غير المصرح بها 401، وتُعيد مُدخلات المهمة غير الصالحة 400، وتُعيد أخطاء طلبات SDK الرمز 502. إرجاع مهمة حالتها failed نتيجة مختلفة عن فشل طلب HTTP.

انتهاء المهلة لا يثبت فشل الإنشاء. إلغاء سياق الطلب يوقف الانتظار المحلي، وليس المهمة البعيدة. لا تعيد SDK مطلقًا محاولة POST الخاص بالإنشاء تلقائيًا.

1. 1.

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

   استخدم مسار GET مع ذلك المعرّف. عند حدوث أخطاء SDK، تتضمن استجابة الخطأ بصيغة JSON في المثال الحقلين taskId وrequestId عندما تتيحهما SDK.

2. 2.

   إذا لم يكن لديك سوى معرّف الطلب، فأعد إرسال طلب الإنشاء الأصلي

   أرسل POST مجددًا بالقيمة نفسها لـ X-Request-ID ودون تغيير مُدخلات المهمة. يعني ذلك إبقاء اسم المضيف والإجراء والبروكسي المضبوطة دون تغيير. يستعيد معرّف الطلب نفسه وطلب المهمة نفسه المهمة الحالية؛ أما المُدخلات المختلفة مع ذلك المعرّف فتسبب تعارضًا.

3. 3.

   احتفظ بالمعرّف قبل الطلب الأول

   تنشئ SDK معرّف طلب عند عدم توفيره، لكن المستدعي الذي انقطع اتصاله قد لا يتلقاه أبدًا. اختيار X-Request-ID والاحتفاظ به قبل POST يجنبك الاعتماد على استجابة الخطأ للاستعادة.

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

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