Gin işleyicisinde Go SDK'sını kullanın

1. 1.

   Go modülünü oluşturun ve bağımlılıkları yükleyin

   Güncel Gin sürümü için Go 1.25 veya üzerini kullanın. solvethree SDK’sının kendisi Go 1.22+ gerektirir. Kendi modül yolunuzu kullanarak uygulamanızın modülünü go mod init ile başlatın. Gin’i hızlı başlangıç kılavuzunu izleyerek yükleyin, ardından solvethree.com/[email protected] eklemek için go get kullanın. Resmî SDK, alan adında barındırılan herkese açık modül proxy’si üzerinden sunulur; solvethree.com adresinden sağlanır.

2. 2.

   Sunucu kimlik bilgilerini ayarlayın

   SOLVETHREE_API_KEY değerini çalışma alanınızın API anahtarı, INTEGRATION_KEY değerini ise dahili uygulamanızın X-Integration-Key içinde göndereceği gizli anahtar olarak ayarlayın. Bunlar ayrı kimlik bilgileridir: uygulamayı çağıranın solvethree API anahtarına ihtiyacı yoktur.

3. 3.

   Sabit hedefi yapılandırın

   CAPTCHA_SITE değerini hedef ana makine adı, SOLVETHREE_PROXY değerini ise çözüm için kullanılan proxy olarak ayarlayın. Önce çalışma alanında etkin bir site profili oluşturun; site profili kurulumuna bakın. Örnek, Action değerini login olarak sabitler; entegrasyonunuz başka bir eylem kullanıyorsa bu değeri değiştirin. Ana makine adını ve eylemi ayarlamak profil oluşturmaz.

İstemci bir kez oluşturulur ve eşzamanlı isteklerde güvenle kullanılabilir. Rota, solvethree’yi çağırmadan önce dahili uygulamanın kimlik bilgisini kontrol eder. Çağırandan bir istek kimliği kabul eder, ancak keyfî bir hedef veya proxy kabul etmez.

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"))
}

Görev, Site, Action ve tek bir Proxy sağlar. reCAPTCHA için gerektiği gibi Type ve URL alanlarını ayarlamaz ve varsayılan Enterprise v3 modunu kullanır.

Bağlam için açıkça belirlenen son süre, işleyicinin beklemesini 180 saniyeyle sınırlar; istemci bağlantısının kesilmesi işlemi daha erken iptal edebilir. HTTP sunucusu ve varsa ters proxy bu istek süresine izin vermelidir. İzin veremiyorlarsa bu senkron rotayı açık tutmak yerine ayrı oluşturma/sorgulama işlemleri kullanın.

Dinleyici loopback adresine bağlanır. Rotayı uygulamanızın mevcut dahili kimlik doğrulama ve dağıtım düzenine entegre edin; çağıranın kimliğini doğrulamadan ücretli bir çözüm uç noktasını erişime açmayın.

İşleyici, hata metinlerini eşleştirmek yerine errors.As kullanır. Nihai bir TaskFailedError, görev kimliğini ve hata kodunu içeren bir 502 yanıtı üretir. Sarmalanmış diğer SDK hataları, yeniden erişim kimliklerini içeren bir 502 yanıtı üretir. Son çare hata işleme yolu, ham hataları, kimlik bilgilerini veya proxy URL’lerini açığa çıkarmak yerine sabit bir 400 mesajı döndürür.

Bu 502 yanıtlarının hepsi çözümün başarısız olduğu anlamına gelmez. İptal ile sürenin dolmasını ayırt etmek için errors.Is kullanın. HTTP'ye özgü işlemler için errors.As, StatusCode ve RetryAfter içeren iç içe bir APIError çıkarabilir. Her hatayı yeni bir görev oluşturma nedeni saymak yerine bu ayrımı dahili tanılama kayıtlarında koruyun.

Nihai olarak başarısız olmuş bir görev yeniden sorgulanmamalıdır. Hata metnine ihtiyacınız varsa görevi alın, ardından başka bir çözüm başlatmadan önce hatanın nedenini giderin. Başarısız çözümlerin ücreti iade edilir.

İptal, uzaktaki işlemi değil beklemeyi durdurur. Örnek, mümkün olduğunda kurtarma kimliklerini döndürür ancak bunları kalıcı olarak saklamaz. Çağrıyı yapan tarafın bağlantısı kesilirse bu JSON yanıtı hiç ulaşmayabilir.

1. 1.

   Rotayı çağırmadan önce istek kimliğini atayın

   Dahili çağrıyı yapan bileşenin her mantıksal çözüm işlemi için sabit bir X-Request-ID saklamasını sağlayın. Geçerli kimlikler 1–64 ASCII harfi, rakam, alt çizgi veya kısa çizgi içerir. Kimlik eksik olduğunda SDK bir kimlik üretir; ancak bunu önceden atamak, yanıt kaybolsa bile kurtarmayı mümkün kılar.

2. 2.

   Görev girdilerini aynen saklayın

   Ana makine adını, eylemi, proxy'yi ve istek kimliğini korumalı uygulama depolamasında saklayın. Ortam yapılandırması değiştikten sonra yapılan yeniden denemeler, görev girdilerini sessizce farklı girdilerle değiştirmemelidir.

3. 3.

   Yeni bir işlem oluşturmadan önce mevcut işlemi kurtarın

   Görev kimliği biliniyorsa yeni ve süre sınırı olan bir bağlamla GetTask çağrısı yapın. Kimlik bilinmiyorsa özgün görevi aynı istek kimliği ve girdilerle CreateTask üzerinden yeniden gönderin. Bu, mevcut görevi döndürür; aynı kimlikle farklı girdiler göndermek çakışmaya neden olur. Yalnızca görev beklemede veya çözülüyor durumundayken sorgulamaya devam edin.

Solve görevi bir kez oluşturur ve yalnızca HTTP durumu 429, 502, 503 veya 504 olan geçici sorgulama yanıtlarını yeniden dener; bağlamın son süresi dahilinde Retry-After değerine uyar. CreateTask, POST isteğini hiçbir zaman otomatik olarak yeniden denemez; bu nedenle oluşturma sırasında zaman aşımı olursa yeni bir istek kimliği yerine kurtarma işlemi gerekir.

Başarılı bir işleyici yanıtı, yetkili uygulama çağırıcısına özel çözüm verileri içerir. Hedef istekte görev kimliğini değil, Solution.Token kullanın. Döndürülen UserAgent ve SecChUA değerlerini kullanın ve başarılı proxy'yi SuccessfulProxy(originalTask, readyResult) ile alın.

SDK hedefe hiçbir şey göndermez. Hazır bir görev, bir çözüm üretildiği anlamına gelir; web sitesinin bunu kabul ettiği anlamına gelmez. Hedefin yanıtını ayrıca kontrol edin.