קריאה ל-API של CAPTCHA מתוך Laravel

1. 1.

   הפעלת פרופיל האתר

   הגדירו את שם המארח של היעד במסוף כדי שבסביבת העבודה שלכם יהיה פרופיל reCAPTCHA פעיל. שליחת שם מארח במשימה אינה יוצרת פרופיל. ראו הגדרת פרופיל אתר.

2. 2.

   הוסיפו את תצורת השרת

   הוסיפו את הרשומה solvethree מהדוגמה למערך הקיים ב-config/services.php. הגדירו את SOLVETHREE_API_KEY, CAPTCHA_SITE ו-SOLVETHREE_PROXY בסביבת השרת. אל תכללו את הערכים האלה בקוד הדפדפן; CAPTCHA_SITE הוא שם המארח, לא כתובת URL מלאה.

3. 3.

   התאימו את הפעולה ליעד

   הדוגמה שולחת login. שנו אותו לפעולה שבה משתמשת בקשת היעד המיועדת שלכם. היא מספקת proxy אחד; אל תשלחו גם proxyCandidates.

<?php
// app/Services/CaptchaApi.php — configure services.solvethree in config/services.php.
namespace App\Services;

use Illuminate\Support\Facades\Http;
use InvalidArgumentException;

final class CaptchaApi
{
    private function client()
    {
        return Http::baseUrl('https://api.solvethree.com/v1')
            ->withToken(config('services.solvethree.key'))
            ->acceptJson()->asJson()->connectTimeout(10)->timeout(25);
    }

    public function create(string $requestId): array
    {
        if (!preg_match('/^[A-Za-z0-9_-]{1,64}$/', $requestId)) {
            throw new InvalidArgumentException('Invalid logical request ID');
        }
        // The caller keeps this requestId; do not generate another on a timeout.
        return $this->client()->post('/tasks?waitMs=0', [
            'site' => config('services.solvethree.site'),
            'action' => 'login',
            'proxy' => config('services.solvethree.proxy'),
            'requestId' => $requestId,
        ])->throw()->json();
    }

    public function retrieve(string $taskId): array
    {
        if (!preg_match('/^[A-Za-z0-9_-]{1,128}$/', $taskId)) {
            throw new InvalidArgumentException('Invalid task ID');
        }
        return $this->client()->get('/tasks/'.rawurlencode($taskId), ['waitMs' => 15000])
            ->throw()->json();
    }
}
// config/services.php entry:
// 'solvethree' => ['key' => env('SOLVETHREE_API_KEY'),
//   'site' => env('CAPTCHA_SITE'), 'proxy' => env('SOLVETHREE_PROXY')],
// Invoke from your authenticated controller/job. Poll retrieve only while pending
// or solving; ready contains the solution, failed is terminal. Never use retry()
// on create without preserving both this ID and the exact original inputs.

withToken שולח את מפתח סביבת העבודה באמצעות אימות Bearer. גוף ה-POST שטוח: site, action, proxy ו-requestId הם שדות ברמה העליונה. אל תוסיפו שדה type או url עבור reCAPTCHA. השמטת recaptchaType בוחרת בברירת המחדל המתועדת enterprise-v3.

שתי המתודות קוראות ל-throw() לפני json(). לקוח ה-HTTP של Laravel אינו זורק חריגות עבור תגובות HTTP לא מוצלחות כברירת מחדל, ולכן כך נמנע מהקורא לפרש תוכן של שגיאת HTTP כתגובת משימה מוצלחת. השירות מגדיר זמני המתנה לחיבור ולבקשה, ובמכוון אינו מבצע ניסיונות POST חוזרים אוטומטיים.

1. 1.

   צרו פעם אחת לכל בקשת פתרון לוגית

   בבקר או במשימת הרקע המאומתים שלכם, שמרו requestId שנוצר בידי הקורא לפני הקריאה ל-create. עליו להכיל 1–64 אותיות ASCII, ספרות, קווים תחתונים או מקפים. שמרו בנפרד את מזהה המשימה שהוחזר: מזהה הבקשה הלוגי מיועד לשחזור היצירה; מזהה המשימה הוא הערך ש-retrieve מקבל.

2. 2.

   אחזור המשימה הקיימת

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

3. 3.

   טפלו בתוצאה הסופית

   במצב failed, הפסיקו לאחזר ובדקו את errorCode ואת error; על פתרונות שנכשלו ניתן החזר. במצב ready, השתמשו באסימון הפתרון שהוחזר. שלחו אותו עם זהות userAgent ו-secChUa שהוחזרה ועם אותו פרוקסי ששימש לפתרון. פתרון מוכן עדיין צריך להתקבל ביעד.

הפרידו בין שגיאות HTTP לכשלים במשימה. תגובת HTTP לא מוצלחת מטופלת באמצעות throw(); תגובה מוצלחת שמכילה failed מחייבת טיפול ברמת המשימה. אל תנסו שוב עם קלט לא תקין שלא השתנה, ואל תניחו שכל כשל מעיד על יתרה לא מספקת. ראו טיפול בשגיאות API.

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