שימוש ב-SDK של Go במטפל של Gin

1. 1.

   יצירת מודול Go והתקנת תלויות

   השתמשו ב-Go 1.25 או בגרסה מאוחרת יותר עבור הגרסה הנוכחית של Gin. ה-SDK של solvethree עצמו דורש Go 1.22+. אתחלו את מודול האפליקציה באמצעות go mod init, תוך שימוש בנתיב המודול שלכם. התקינו את Gin לפי מדריך ההתחלה המהירה שלו, ואז השתמשו ב-go get כדי להוסיף את solvethree.com/[email protected]. ה-SDK הרשמי מוגש דרך פרוקסי המודולים הציבורי שמתארח בדומיין; הוא מוגש מ-solvethree.com.

2. 2.

   הגדרת פרטי הגישה בשרת

   הגדירו את SOLVETHREE_API_KEY למפתח ה-API של סביבת העבודה ואת INTEGRATION_KEY לסוד שהאפליקציה הפנימית שלכם תשלח ב-X-Integration-Key. אלה פרטי גישה נפרדים: הפונה לאפליקציה אינו זקוק למפתח ה-API של solvethree.

3. 3.

   הגדרת היעד הקבוע

   הגדירו את CAPTCHA_SITE לשם מארח היעד ואת SOLVETHREE_PROXY לפרוקסי שישמש לפתרון. תחילה צרו פרופיל אתר פעיל בסביבת העבודה; ראו הגדרת פרופיל אתר. הדוגמה מקבעת את Action לערך login, לכן שנו את הערך הזה אם האינטגרציה שלכם משתמשת בפעולה אחרת. הגדרת שם המארח והפעולה אינה יוצרת פרופיל.

הלקוח נוצר פעם אחת ובטוח לשימוש בבקשות מקבילות. הנתיב בודק את פרטי הגישה של האפליקציה הפנימית לפני הקריאה ל-solvethree. הוא מקבל מזהה בקשה מהקורא, אך לא יעד או פרוקסי שרירותיים.

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 יחיד. היא משאירה את Type ואת URL ללא ערך, כנדרש עבור reCAPTCHA, ומשתמשת במצב Enterprise v3 המוגדר כברירת מחדל.

מועד הסיום המפורש של ההקשר מגביל את ההמתנה של פונקציית הטיפול ל-180 שניות; ניתוק הלקוח יכול לבטל אותה מוקדם יותר. שרת ה-HTTP וכל פרוקסי הפוך חייבים לאפשר בקשה במשך הזמן הזה. אם אינם יכולים, השתמשו בפעולות יצירה ושליפה נפרדות במקום להשאיר את הנתיב הסינכרוני הזה פתוח.

המאזין נקשר לכתובת loopback. שלבו את הנתיב במערך האימות הפנימי והפריסה הקיים של האפליקציה שלכם; אל תחשפו נקודת קצה לפתרון בתשלום ללא אימות הפונה.

פונקציית הטיפול משתמשת ב-errors.As במקום בהתאמת מחרוזות שגיאה. שגיאת TaskFailedError סופית מפיקה תגובת 502 שמכילה את מזהה המשימה ואת קוד השגיאה. שגיאות SDK עטופות אחרות מפיקות תגובת 502 שמכילה מזהי שחזור. במקרה שאינו מכוסה, מוחזרת הודעת 400 קבועה במקום לחשוף שגיאות גולמיות, פרטי גישה או כתובות URL של פרוקסי.

לא כל תגובות ה-502 האלה מעידות שהפתרון נכשל. השתמשו ב-errors.Is כדי להבחין בין ביטול לבין חלוף המועד האחרון. לטיפול ייעודי ב-HTTP, אפשר להשתמש ב-errors.As כדי לחלץ APIError מקונן עם StatusCode ו-RetryAfter. שמרו על ההבחנה הזו באבחון הפנימי, במקום להתייחס לכל שגיאה כסיבה ליצור משימה נוספת.

אין להמשיך לתשאל משימה שהסתיימה בכישלון. אחזרו אותה אם אתם זקוקים לטקסט השגיאה שלה, ואז תקנו את הגורם לפני התחלת פתרון נוסף. על פתרונות שנכשלו ניתן החזר כספי.

ביטול מפסיק את ההמתנה, לא את העבודה המרוחקת. הדוגמה מחזירה מזהים לשחזור כשהדבר אפשרי, אבל אינה שומרת אותם באחסון מתמיד. אם הגורם הקורא מתנתק, ייתכן שתגובת ה-JSON הזו לעולם לא תגיע.

1. 1.

   הקצו מזהה בקשה לפני הקריאה לנתיב

   דאגו שהגורם הקורא הפנימי ישמור X-Request-ID קבוע לכל פעולת פתרון לוגית. מזהים תקינים מכילים 1–64 תווי ASCII: אותיות, ספרות, קווים תחתונים או מקפים. ה-SDK מייצר מזהה כשלא מסופק מזהה, אבל הקצאתו מראש מאפשרת שחזור גם אם התגובה אובדת.

2. 2.

   שמרו את קלטי המשימה המדויקים

   שמרו את שם המארח, הפעולה, הפרוקסי ומזהה הבקשה באחסון יישום מוגן. ניסיון חוזר לאחר שינוי בתצורת הסביבה לא אמור להחליף את קלטי המשימה בקלטים אחרים ללא ידיעתכם.

3. 3.

   שחזרו לפני יצירת עבודה חדשה

   אם מזהה המשימה ידוע, קראו ל-GetTask עם הקשר חדש שמוגבל בזמן. אם הוא אינו ידוע, שלחו שוב את המשימה המקורית דרך CreateTask עם אותם מזהה בקשה וקלטים. כך תוחזר המשימה הקיימת; קלטים שונים עם אותו מזהה יוצרים התנגשות. המשיכו לאחזר רק כל עוד המשימה ממתינה או נמצאת בתהליך פתרון.

Solve יוצר פעם אחת ומנסה שוב רק תגובות תשאול זמניות עם סטטוס HTTP של 429, 502, 503 או 504, תוך כיבוד Retry-After במסגרת המועד האחרון של ההקשר. CreateTask לעולם אינו מנסה שוב POST באופן אוטומטי, ולכן אם פג הזמן הקצוב ליצירה, עדיין נדרש שחזור ולא מזהה בקשה חדש.

תגובה מוצלחת של המטפל מכילה נתוני פתרון פרטיים עבור הגורם המורשה שקורא מתוך היישום. השתמשו ב-Solution.Token, ולא במזהה המשימה, בבקשה ליעד. השתמשו ב-UserAgent וב-SecChUA שהוחזרו, וקבלו את הפרוקסי שהצליח באמצעות SuccessfulProxy(originalTask, readyResult).

ה-SDK אינו שולח דבר ליעד. משימה מוכנה פירושה שנוצר פתרון, לא שהאתר קיבל אותו. בדקו את תגובת היעד בנפרד.