פתרון reCAPTCHA Enterprise באמצעות Node.js

התקינו את החבילה הרשמית ישירות מ-solvethree.com:

npm install https://solvethree.com/downloads/solvethree-sdk-0.1.0.tgz

1. 1.

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

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

2. 2.

   הגדרת סביבת השרת

   בסביבת התהליך של Node.js, הגדירו את SOLVETHREE_API_KEY למפתח ה-API של סביבת העבודה ואת SOLVETHREE_PROXY לכתובת הפרוקסי שלכם. שמרו את מפתח ה-API בשרת; אל תחשפו אותו בקוד דפדפן.

3. 3.

   הכנת הסקריפט

   שמרו את הדוגמה הבאה בשם solve.mjs. החליפו את accounts.example.com בשם המארח שהגדרתם ואת login בפעולת ה-reCAPTCHA האמיתית של העמוד.

השתמשו בשם מארח עבור site, לא בכתובת URL של עמוד. ברירת המחדל של reCAPTCHA היא enterprise-v3, ולכן הדוגמה אינה זקוקה ל-recaptchaType. אל תוסיפו type או url. הבקשה דורשת בדיוק אחד מבין proxy או proxyCandidates; דוגמה זו משתמשת בפרוקסי יחיד.

import { randomUUID } from 'node:crypto';
import { Solvethree, SolvethreeError, TaskFailedError } from '@solvethree/sdk';

const client = new Solvethree({ apiKey: process.env.SOLVETHREE_API_KEY });
const request = {
  site: 'accounts.example.com', // Use your configured hostname.
  action: 'login',              // Use the page's actual action.
  proxy: process.env.SOLVETHREE_PROXY,
  requestId: randomUUID(),
};
let result;
try {
  result = await client.solve(request, { timeoutMs: 180_000 });
} catch (error) {
  if (error instanceof TaskFailedError) {
    throw new Error(`Task failed: ${error.errorCode}`);
  }
  if (error instanceof SolvethreeError) {
    // Save these IDs; use them to recover the existing task.
    console.error({ requestId: error.requestId, taskId: error.taskId });
  }
  throw error;
}
const { token, userAgent, secChUa } = result.solution;
console.log('Ready task:', result.id); // Keep solution credentials private.

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

לשדות המוחזרים יש תפקידים שונים:

• result.id מזהה את המשימה. הוא אינו טוקן ה-CAPTCHA.
• result.solution.token הוא הערך שיש לשלוח בשדה ה-CAPTCHA של היישום.
• result.solution.userAgent ו-result.solution.secChUa הם זהות הדפדפן שיש להשתמש בה עם הטוקן הזה.

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

המשיכו באותו סקריפט לאחר ש-solve חוזר. דוגמה זו משתמשת ב-undici, שיש להתקין בנפרד כפי שמתואר בהערה שבה. היא שולחת את הטוקן באמצעות request.proxy ומשתמשת בשני שדות זהות הדפדפן שהוחזרו.

// Continue after client.solve(). Install undici separately: npm install undici@7.
import { fetch, ProxyAgent } from 'undici';

const dispatcher = new ProxyAgent(request.proxy);
try {
  // Replace the URL and form fields with your application's contract.
  const response = await fetch('https://accounts.example.com/login', {
    method: 'POST',
    dispatcher,
    redirect: 'manual',
    headers: {
      'user-agent': result.solution.userAgent,
      'sec-ch-ua': result.solution.secChUa,
    },
    body: new URLSearchParams({
      'g-recaptcha-response': result.solution.token,
    }),
    signal: AbortSignal.timeout(30_000),
  });
  console.log('Application HTTP status:', response.status);
  await response.arrayBuffer();
} finally {
  await dispatcher.close();
}

החליפו את כתובת ה-URL ואת שדות הטופס בהתאם לממשק של היישום שלכם. הדוגמה מספקת רק את g-recaptcha-response; כללו כל שדה ונתון הפעלה נוסף שהיישום דורש. ודאו שהיעד תואם לאתר ולפעולה שעבורם פתרתם.

מכיוון שבקשת הפתרון משתמשת בפרוקסי אחד, שימוש חוזר ב-request.proxy משאיר את השליחה באותו פרוקסי. אם תשנו את הבקשה לשימוש ב-proxyCandidates, בחרו במקום זאת את הפרוקסי שהצליח באמצעות פונקציית העזר successfulProxy של ה-SDK.

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

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

solve זורק TaskFailedError

החריגה כוללת errorCode ו-taskId. קראו ל-getTask(taskId) אם נדרשת התגובה המלאה של המשימה שנכשלה, כולל טקסט השגיאה שלה.

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

SolvethreeError כולל taskId

ל-SDK יש מזהה של המשימה הקיימת.

כדאי לנסות: חדשו את התשאול באמצעות getTask. המשיכו במצבי pending או solving, השתמשו בפתרון רק במצב ready, והפסיקו במצב failed.

היצירה נקטעת ורק requestId זמין

חריגה מהזמן הקצוב לחיבור אינה מוכיחה שהמשימה לא נוצרה.

כדאי לנסות: שחזרו באמצעות createTask עם קלט זהה למשימה ואותו requestId. שימוש חוזר במזהה הזה עם קלט שונה יוצר התנגשות.

ה-API דוחה בקשת HTTP

בדקו את קוד מצב ה-HTTP שמספק ApiError במקום להתייחס לתגובה כאל משימה מוכנה או משימה שנכשלה.

כדאי לנסות: טפלו בשגיאת ה-HTTP לפני עיבוד תוכן של תגובת הצלחה. אל תניחו שכל כשל נובע מיתרה לא מספקת.

הדוגמה יוצרת requestId חדש בכל הפעלה של התוכנית. הרצתה מחדש ללא שינוי אינה שחזור: השתמשו במקום זאת בבקשה ובמזהים ששמרתם. ה-SDK לעולם אינו מנסה שוב באופן אוטומטי ליצור משימות; הוא כן מכבד את Retry-After במקרה של כשלי תשאול זמניים, במסגרת הזמן הקצוב לפתרון.

להגדרות מפורשות של תשאול והמתנה, ראו תשאול משימות וזמני קצוב.