Gin हैंडलर में Go SDK का उपयोग करें

1. 1.

   Go मॉड्यूल बनाएँ और डिपेंडेंसी इंस्टॉल करें

   मौजूदा Gin रिलीज़ के लिए Go 1.25 या बाद का संस्करण उपयोग करें। solvethree SDK को स्वयं Go 1.22+ चाहिए। अपने मॉड्यूल पाथ के साथ go mod init का उपयोग करके अपने एप्लिकेशन का मॉड्यूल इनिशियलाइज़ करें। इसकी क्विकस्टार्ट गाइड के अनुसार Gin इंस्टॉल करें, फिर solvethree.com/[email protected] जोड़ने के लिए go get का उपयोग करें। आधिकारिक SDK डोमेन पर होस्ट किए गए सार्वजनिक मॉड्यूल प्रॉक्सी के ज़रिए उपलब्ध कराया जाता है; इसे solvethree.com से सर्व किया जाता है।

2. 2.

   सर्वर क्रेडेंशियल सेट करें

   SOLVETHREE_API_KEY को अपने वर्कस्पेस की API की पर और INTEGRATION_KEY को उस सीक्रेट पर सेट करें जिसे आपका आंतरिक एप्लिकेशन X-Integration-Key में भेजेगा। ये अलग-अलग क्रेडेंशियल हैं: एप्लिकेशन कॉलर को solvethree API की की ज़रूरत नहीं है।

3. 3.

   स्थिर लक्ष्य कॉन्फ़िगर करें

   CAPTCHA_SITE को लक्ष्य होस्टनेम पर और SOLVETHREE_PROXY को सॉल्व के लिए उपयोग होने वाली प्रॉक्सी पर सेट करें। पहले वर्कस्पेस में एक सक्रिय साइट प्रोफ़ाइल बनाएँ; साइट प्रोफ़ाइल सेटअप देखें। उदाहरण में Action का मान login पर स्थिर है, इसलिए यदि आपका इंटीग्रेशन कोई अन्य एक्शन उपयोग करता है, तो यह मान बदलें। होस्टनेम और एक्शन सेट करने से प्रोफ़ाइल नहीं बनती।

क्लाइंट एक बार बनाया जाता है और समवर्ती अनुरोधों के लिए सुरक्षित है। solvethree कॉल करने से पहले रूट आंतरिक एप्लिकेशन के क्रेडेंशियल की जाँच करता है। यह कॉलर से अनुरोध ID स्वीकार करता है, लेकिन मनमाना लक्ष्य या प्रॉक्सी नहीं।

package main

import (
    "context"
    "errors"
    "log"
    "net/http"
    "os"
    "time"
    "github.com/gin-gonic/gin"
    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") }
    router:=gin.New()
    router.Use(gin.Recovery())
    router.POST("/captcha/solve",func(c *gin.Context){
        if c.GetHeader("X-Integration-Key")!=secret { c.Status(http.StatusUnauthorized);return }
        input:=solvethree.TaskRequest{Site:os.Getenv("CAPTCHA_SITE"),Action:"login",
            Proxy:os.Getenv("SOLVETHREE_PROXY"),RequestID:c.GetHeader("X-Request-ID")}
        ctx,cancel:=context.WithTimeout(c.Request.Context(),180*time.Second);defer cancel()
        result,err:=client.Solve(ctx,input,solvethree.SolveOptions{})
        if err!=nil {
            var failed *solvethree.TaskFailedError
            var recovery *solvethree.Error
            if errors.As(err,&failed) { c.JSON(502,gin.H{"taskId":failed.TaskID,"errorCode":failed.ErrorCode});return }
            if errors.As(err,&recovery) { c.JSON(502,gin.H{"requestId":recovery.RequestID,"taskId":recovery.TaskID});return }
            c.JSON(400,gin.H{"error":"Invalid task input"});return
        }
        // Return private solution data only to the authorized application caller.
        c.JSON(200,result)
    })
    log.Fatal(router.Run("127.0.0.1:3000"))
}

टास्क Site, Action और एक Proxy देता है। reCAPTCHA की आवश्यकता के अनुसार, यह Type और URL को सेट नहीं करता और डिफ़ॉल्ट Enterprise v3 मोड का उपयोग करता है।

स्पष्ट रूप से सेट की गई कॉन्टेक्स्ट समय-सीमा हैंडलर की प्रतीक्षा को 180 सेकंड तक सीमित करती है; क्लाइंट का कनेक्शन टूटने पर यह उससे पहले रद्द हो सकती है। HTTP सर्वर और किसी भी रिवर्स प्रॉक्सी को उतनी अनुरोध अवधि की अनुमति देनी चाहिए। यदि वे ऐसा नहीं कर सकते, तो इस सिंक्रोनस रूट को खुला रखने के बजाय अलग-अलग बनाने/प्राप्त करने के ऑपरेशन उपयोग करें।

लिसनर लूपबैक से बाइंड होता है। रूट को अपने एप्लिकेशन के मौजूदा आंतरिक प्रमाणीकरण और डिप्लॉयमेंट सेटअप के साथ इंटीग्रेट करें; कॉलर के प्रमाणीकरण के बिना सशुल्क सॉल्व एंडपॉइंट उपलब्ध न कराएँ।

हैंडलर त्रुटि स्ट्रिंग का मिलान करने के बजाय errors.As का उपयोग करता है। अंतिम TaskFailedError पर 502 रिस्पॉन्स मिलता है जिसमें टास्क ID और त्रुटि कोड होते हैं। अन्य रैप की गई SDK त्रुटियाँ 502 लौटाती हैं जिसमें रिकवरी ID होती हैं। फ़ॉलबैक, रॉ त्रुटियाँ, क्रेडेंशियल या प्रॉक्सी URL उजागर करने के बजाय एक निश्चित 400 संदेश लौटाता है।

इन सभी 502 प्रतिक्रियाओं का मतलब यह नहीं है कि समाधान विफल हुआ। रद्दीकरण या समय-सीमा समाप्त होने में अंतर करने के लिए errors.Is का उपयोग करें। HTTP-विशिष्ट हैंडलिंग के लिए, errors.As किसी नेस्टेड APIError को उसके StatusCode और RetryAfter सहित निकाल सकता है। हर त्रुटि को नया टास्क बनाने का कारण मानने के बजाय, आंतरिक निदान में यह अंतर बनाए रखें।

अंतिम रूप से विफल टास्क को दोबारा पोल नहीं करना चाहिए। उसका त्रुटि संदेश चाहिए तो उसे प्राप्त करें, फिर नया समाधान शुरू करने से पहले कारण ठीक करें। विफल समाधानों का शुल्क वापस किया जाता है।

रद्दीकरण प्रतीक्षा रोकता है, रिमोट काम नहीं। यह उदाहरण जहाँ संभव हो रिकवरी ID लौटाता है, लेकिन उन्हें स्थायी रूप से सहेजता नहीं है। कॉलर का कनेक्शन टूटने पर वह JSON प्रतिक्रिया शायद कभी न पहुँचे।

1. 1.

   रूट कॉल करने से पहले अनुरोध ID तय करें

   आंतरिक कॉलर से हर तार्किक समाधान के लिए एक स्थिर X-Request-ID सुरक्षित रखवाएँ। मान्य ID में 1–64 ASCII अक्षर, अंक, अंडरस्कोर या हाइफ़न होते हैं। ID न होने पर SDK उसे बनाता है, लेकिन पहले से तय करने पर प्रतिक्रिया खो जाने पर भी रिकवरी संभव होती है।

2. 2.

   टास्क के मूल इनपुट ज्यों के त्यों सुरक्षित रखें

   होस्टनाम, ऐक्शन, प्रॉक्सी और अनुरोध ID को एप्लिकेशन के सुरक्षित स्टोरेज में रखें। एनवायरनमेंट कॉन्फ़िगरेशन बदलने के बाद दोबारा प्रयास करते समय टास्क के इनपुट बिना बताए नहीं बदलने चाहिए।

3. 3.

   नया काम बनाने से पहले रिकवरी करें

   टास्क ID पता हो तो नई, सीमित समय-सीमा वाले कॉन्टेक्स्ट के साथ GetTask कॉल करें। ID न हो तो उसी अनुरोध ID और इनपुट के साथ मूल टास्क को CreateTask के ज़रिए दोबारा भेजें। इससे मौजूदा टास्क लौटता है; एक ही ID के साथ अलग इनपुट देने पर टकराव होता है। टास्क लंबित हो या हल किया जा रहा हो, केवल तभी उसे प्राप्त करते रहें।

Solve एक बार टास्क बनाता है और केवल HTTP स्टेटस 429, 502, 503 या 504 वाली अस्थायी पोलिंग प्रतिक्रियाओं पर दोबारा प्रयास करता है, कॉन्टेक्स्ट की समय-सीमा के भीतर Retry-After का पालन करते हुए। CreateTask कभी भी POST का अपने-आप दोबारा प्रयास नहीं करता, इसलिए निर्माण का समय समाप्त होने पर भी नई अनुरोध ID के बजाय रिकवरी आवश्यक है।

सफल हैंडलर प्रतिक्रिया में अधिकृत एप्लिकेशन कॉलर के लिए निजी समाधान डेटा होता है। लक्ष्य अनुरोध में टास्क ID नहीं, Solution.Token का उपयोग करें। लौटाए गए UserAgent और SecChUA का उपयोग करें और सफल प्रॉक्सी पाने के लिए SuccessfulProxy(originalTask, readyResult) का उपयोग करें।

SDK लक्ष्य को कुछ भी सबमिट नहीं करता। तैयार टास्क का मतलब है कि समाधान बन गया है, यह नहीं कि वेबसाइट ने उसे स्वीकार कर लिया है। लक्ष्य की प्रतिक्रिया अलग से जाँचें।